> ## Documentation Index
> Fetch the complete documentation index at: https://developers.qomon.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Update contact by ID
> Fully replace an existing contact in the Qomon database (behaves like PUT).
This endpoint uses the PATCH verb but behaves like a PUT (full replacement). Any fields that are NOT included in the payload will be cleared/removed. Always send the full contact object if you don't want to lose existing data. To synchronize and mass update your contacts with Qomon database, use `POST /contacts/upsert` instead. This synchronous endpoint costs 5 rate-limit tokens per request.To specify the advanced fields (survey, consents, etc), you need to use the `formdatas` structure with `form_id` and `form_ref_id`.
* `form_id`: the ID of the advanced field
* `form_ref_id`: the ID of the value of the advanced field
* `data`: free text if the field ("forms") type is Text, Integer, or Date (input format: `YYYY-MM-DD'T'HH:mm:ss.SSS'Z'`; responses may return up to microsecond precision: `YYYY-MM-DD'T'HH:mm:ss.SSSSSS'Z'`); otherwise, use the value of the refvalue
* `date`: the date of the formdata entry
```json
"formdatas": [
{
"form_id": 47566,
"form_ref_id": 15648,
"data": "consent_email"
}
]
```
To specify the custom fields, you need to use the `custom_fields` structure with `form_id` and `form_ref_id`.
* `form_id`: the ID of the custom field
* `form_ref_id`: the ID of the value of the custom field
* `data`: free text if the field ("forms") type is Text, Integer, or Date (input format: `YYYY-MM-DD'T'HH:mm:ss.SSS'Z'`; responses may return up to microsecond precision: `YYYY-MM-DD'T'HH:mm:ss.SSSSSS'Z'`); otherwise, use the value of the refvalue
* `date`: the date of the custom\_field entry
```json
"custom_fields": [
{
"form_id": 879854,
"form_ref_id": 98741,
"data": "hamburger",
"date": "2024-07-17T11:34:42.195Z"
}
]
```
NB:
* Each patch will generate new ids for formdatas and custom\_fields. (due to the full replace behavior: soft delete + recreate)
* If you don't send the exhaustive list of formdatas or custom\_fields, the missing ones will be deleted (soft).
* For Text, Integer and Date Fields, if you add a formdata or custom\_field, it will be added to the existing ones.
* For Radio (single select), if you add a formdata or custom\_field, it will replace the existing ones.
* For Checkbox (multi-select) fields, any new value will be added to the existing ones.
* If you change a formdata or custom\_field, it will update it. (the id is not required here because of the full-replace behavior).
## OpenAPI
````yaml /src/autogen/incoming-openapi3.0.yaml patch /contacts/{contactId}
openapi: 3.1.0
info:
description: >-
This OpenAPI 3.1 specification describes the public API of the Qomon
platform. It is generated from the code and serves both as documentation for
API consumers and as a contract for future development.
title: Qomon API Reference
version: 0.0.1
servers:
- description: Production
url: https://incoming.qomon.app
security:
- bearerAuth: []
tags:
- description: >-
Create, read, update, and delete Qomon contacts.
**Basic fields:** name, email, phone, address, tags, gender, birthdate,
etc.
**Advanced fields:** consents, surveys, custom fields, level of support,
tasks.
**Operations:**
- `/contacts/upsert` (async) — Recommended for synchronizing and
mass-updating contacts
- `/contacts` (sync) — Create individual contacts
- `/contacts/{id}` (sync) — Read, update, or delete individual contacts
name: Contacts
- description: >-
Retrieve form definitions and their possible values (refvalues).
**Use forms to:**
- Understand and interpret contact advanced fields
- Look up valid values for consents, surveys, custom fields, task
assignments
- Explore available form types and their structure
**Form types:** consent, level_of_support, presence_status, custom_fields,
survey, tasks
name: Forms
paths:
/contacts/{contactId}:
patch:
tags:
- Contacts
summary: Update contact by ID
description: >-
Fully replace an existing contact in the Qomon database (behaves like
PUT).
operationId: update-contact
parameters:
- description: Contact ID.
in: path
name: contactId
required: true
schema:
description: Contact ID.
examples:
- 42
format: int64
minimum: 0
type: integer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DataEnvelopeContactDataWrapper'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/StatusEnvelopeContactDataWrapper'
description: OK
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error
components:
schemas:
DataEnvelopeContactDataWrapper:
additionalProperties: true
properties:
data:
$ref: '#/components/schemas/ContactDataWrapper'
required:
- data
type: object
StatusEnvelopeContactDataWrapper:
additionalProperties: true
properties:
data:
$ref: '#/components/schemas/ContactDataWrapper'
status:
description: Operation result.
examples:
- success
type: string
required:
- status
- data
type: object
ErrorModel:
additionalProperties: true
properties:
detail:
description: >-
A human-readable explanation specific to this occurrence of the
problem.
examples:
- Property foo is required but is missing.
type: string
errors:
description: Optional list of individual error details
items:
$ref: '#/components/schemas/ErrorDetail'
type:
- array
- 'null'
instance:
description: >-
A URI reference that identifies the specific occurrence of the
problem.
examples:
- https://example.com/error-log/abc123
format: uri
type: string
status:
description: HTTP status code
examples:
- 400
format: int64
type: integer
title:
description: >-
A short, human-readable summary of the problem type. This value
should not change between occurrences of the error.
examples:
- Bad Request
type: string
type:
default: about:blank
description: A URI reference to human-readable documentation for the error.
examples:
- https://example.com/errors/example
format: uri
type: string
type: object
ContactDataWrapper:
additionalProperties: true
properties:
contact:
$ref: '#/components/schemas/Contact'
required:
- contact
type: object
ErrorDetail:
additionalProperties: true
properties:
location:
description: >-
Where the error occurred, e.g. 'body.items[3].tags' or
'path.thing-id'
type: string
message:
description: Error message text
type: string
value:
description: The value at the given location
type: object
Contact:
additionalProperties: true
properties:
CreatedAt:
description: Timestamp when the contact was created.
format: date-time
readOnly: true
type: string
UpdatedAt:
description: Timestamp when the contact was last updated.
format: date-time
readOnly: true
type: string
action_ids:
description: IDs of actions of which the contact is targeted.
items:
format: int64
minimum: 0
type: integer
type:
- array
- 'null'
address:
$ref: '#/components/schemas/Address'
description: Postal address.
age_category:
description: Age category.
format: int64
minimum: 0
type: integer
birth_city:
description: City of birth.
type: string
birth_country:
description: Country code of birth.
type: string
birth_dept:
description: Department of birth.
type: string
birthdate:
description: Date of birth.
format: date-time
type: string
black_list:
description: Whether the contact has opted out of communications.
type: boolean
custom_fields:
description: Organisation-defined custom fields.
items:
$ref: '#/components/schemas/CustomField'
type:
- array
- 'null'
firstname:
description: First name.
examples:
- Jane
type: string
formdatas:
description: Organisation-defined form data.
items:
$ref: '#/components/schemas/FormData'
type:
- array
- 'null'
gender:
description: 'Gender. One of: M (Male), F (Female), O (Other). Empty if unknown.'
enum:
- M
- F
- O
examples:
- female
type: string
group_id:
description: ID of the group the contact belongs to.
format: int64
minimum: 0
readOnly: true
type: integer
id:
description: Unique identifier of the contact.
format: int64
minimum: 0
readOnly: true
type: integer
lastchange:
format: date-time
readOnly: true
type:
- string
- 'null'
lastchangeuserid:
format: int64
minimum: 0
readOnly: true
type: integer
mail:
description: Primary email address.
examples:
- jane@example.com
format: email
type: string
married_name:
type: string
membership_code:
description: Membership code (prefix + serial).
type: string
membership_number:
description: >-
Membership serial number assigned when the contact's first
membership is created.
format: int64
minimum: 0
type: integer
mobile:
description: Mobile phone number.
type: string
mobile_invalid:
description: Whether the mobile phone number is invalid.
type: boolean
nationality:
description: Nationality.
type: string
notes:
description: Notes associated with the contact.
items:
$ref: '#/components/schemas/Note'
type:
- array
- 'null'
phone:
description: Landline phone number.
type: string
phone_invalid:
description: Whether the landline phone number is invalid.
type: boolean
surname:
description: Last (family) name.
examples:
- Doe
type: string
tags:
description: Tags attached to the contact.
items:
$ref: '#/components/schemas/Tag'
type:
- array
- 'null'
user_contact_id:
description: ID of the user associated with the contact, if any.
format: int64
type: integer
required:
- id
type: object
Address:
additionalProperties: true
properties:
addition:
description: Additional address info.
type: string
building:
description: Building name or identifier.
type: string
building_type:
description: Type of building.
enum:
- house
- apartment
- office
- other
type: string
city:
description: City name.
examples:
- Paris
type: string
country:
description: Country.
examples:
- France
type: string
county:
description: County or department.
type: string
door:
description: Door or apartment identifier.
type: string
floor:
description: Floor number.
type: string
housenumber:
description: Street number.
examples:
- '12'
type: string
id:
description: Unique identifier of the address.
examples:
- 7
format: int64
minimum: 0
readOnly: true
type: integer
infos:
description: Additional address information.
type: string
latitude:
description: WGS-84 latitude.
examples:
- '48.8606'
readOnly: true
type: string
location:
description: Geocoded location string.
examples:
- 48.8606,2.3376
readOnly: true
type: string
longitude:
description: WGS-84 longitude.
examples:
- '2.3376'
readOnly: true
type: string
pollingstation:
type: string
postalcode:
description: Postal / ZIP code.
examples:
- '75001'
type: string
score:
description: Address geocoding accuracy score 0-1
format: int64
readOnly: true
type: integer
state:
description: State or region.
type: string
street:
description: Street name.
examples:
- Rue de Rivoli
type: string
type: object
CustomField:
additionalProperties: true
properties:
data:
description: Custom field value.
examples:
- XL
type: string
form_id:
description: Form ID.
format: int64
minimum: 0
type: integer
form_ref_id:
description: Form reference ID.
format: int64
minimum: 0
type: integer
id:
description: Custom field definition ID.
format: int64
minimum: 0
readOnly: true
type: integer
required:
- id
- form_id
- form_ref_id
- data
type: object
FormData:
additionalProperties: true
properties:
contact_id:
description: ID of the contact the form data belongs to.
format: int64
minimum: 0
readOnly: true
type: integer
data:
description: Form data value.
examples:
- Some answer
type: string
date:
description: Date of the form data.
format: date-time
type: string
form_id:
description: Form ID.
format: int64
minimum: 0
type: integer
form_ref_id:
description: Form reference ID.
format: int64
minimum: 0
type: integer
group_id:
description: ID of the group the form data belongs to.
format: int64
minimum: 0
readOnly: true
type: integer
id:
description: Form data ID.
format: int64
minimum: 0
readOnly: true
type: integer
survey_id:
description: Survey ID if the form data is from a survey.
format: int64
minimum: 0
type: integer
required:
- id
- form_id
- form_ref_id
- data
type: object
Note:
additionalProperties: true
properties:
contact_id:
format: int64
minimum: 0
type: integer
created_at:
format: date-time
type: string
data:
description: Content of the note.
type: string
group_id:
format: int64
minimum: 0
type: integer
id:
format: int64
minimum: 0
type: integer
only_super_admin:
description: If true, only user with specific permissions can see this note.
type: boolean
pinned:
description: Whether the note is pinned to the top of the contact's page.
type: boolean
updated_at:
format: date-time
type: string
user:
$ref: '#/components/schemas/User'
description: User who created the note.
required:
- id
type: object
Tag:
additionalProperties: true
properties:
name:
description: Tag label.
examples:
- volunteer
type: string
required:
- name
type: object
User:
additionalProperties: true
properties:
CreatedAt:
description: Timestamp when the user was created.
format: date-time
readOnly: true
type: string
UpdatedAt:
description: Timestamp when the user was last updated.
format: date-time
readOnly: true
type: string
address:
description: Street address.
examples:
- 1 rue de la paix
type: string
avatar:
description: Avatar URL.
examples:
- https://example.com/avatar.png
format: uri
type: string
birthdate:
description: Birthdate.
format: date-time
type: string
city:
description: City.
examples:
- Paris
type: string
contacts:
description: Contacts (fiches) linked to this user account.
items:
$ref: '#/components/schemas/ContactRef'
type:
- array
- 'null'
created:
description: Legacy creation timestamp returned by the upstream service.
format: date-time
readOnly: true
type: string
firstname:
description: First name.
examples:
- John
type: string
group_id:
description: IDs of groups the user belongs to.
items:
format: int64
type: integer
type:
- array
- 'null'
id:
description: Unique identifier of the user.
examples:
- 101
format: int64
readOnly: true
type: integer
locale:
description: Locale language.
examples:
- en
type: string
location:
description: Geographic position as lat,lon string.
examples:
- 1.826483,-1.549486
type: string
mail:
description: Email address.
examples:
- john.doe@example.com
format: email
type: string
phone:
description: Phone number.
examples:
- '0123456789'
type: string
postal:
description: Postal code.
examples:
- '75000'
type: string
role_data:
$ref: '#/components/schemas/Role'
description: User role.
status:
description: >-
User status. Comma-separated list of strings. Values:
'available_week_morning,available_week_night,available_holidays,available_weekend,not_set'.
examples:
- available_week_morning,available_weekend
type: string
surname:
description: Last name.
examples:
- Doe
type: string
two_factor_enable:
description: Indicates if two-factor authentication is enabled.
type: boolean
two_factor_method:
description: Two-factor authentication method.
enum:
- email
- totp
type: string
type: object
ContactRef:
additionalProperties: true
properties:
id:
description: Unique identifier of the contact.
examples:
- 42
format: int64
minimum: 0
type: integer
required:
- id
type: object
Role:
additionalProperties: true
properties:
color:
description: Role colour as a hex string.
examples:
- '#DF0D73'
type: string
id:
description: Role ID.
format: int64
minimum: 0
type: integer
mobile:
description: Whether the role has mobile access.
type: boolean
name:
description: Role name.
type: string
order:
description: Display order for roles in role management view.
format: int64
minimum: 0
type: integer
type:
description: Role type.
enum:
- superadmin
- admin
- manager
- user
- custom
type: string
web:
description: Whether the role has web access.
type: boolean
type: object
securitySchemes:
bearerAuth:
bearerFormat: opaque
description: >-
OAuth2 access token. Pass the token in the Authorization header as
`Bearer `. The token is looked up in Redis to resolve the caller
identity.
scheme: bearer
type: http
````