REST API: persons
Create a fusion vector
Combine several vectors into one record.
Purpose
Use this call to store a fusion vector, built from several vectors you supply, for a new person or for an existing one. Send person_id to update an existing person; leave it out to create one.
Request
POST <API_BASE_URL>/person/fusion. All calls are POST under your API address. Replace <API_BASE_URL> with the API address provided with your access.
Send a permanent API token in the token field of the body, or a user token in the token header. See authentication.
Content type: multipart/form-data. Send the fields as a multipart form.
| Field | Type | Required | Description |
|---|---|---|---|
token | string (uuid) | if no header | Your permanent API token. Required unless you send a user token in the token header. |
list_id | string (uuid) | yes | The list that holds the person. |
person_id | string (uuid) | no | An existing person to update. Leave it out to create a person. |
replace_person_id | string (uuid) | no | A person record to replace. |
embeddings | array of string | no | The vectors to combine, base64 encoded. |
new_person_threshold | string or number | no | The match threshold for creating a new person. The value never creates none. |
fields | array of string or string | no | Strings stored with the record for your own business logic. |
Response
An unhandled failure arrives as HTTP 200 with status of error. Read the body.
HTTP 201. The fusion vector was written to the index and to storage.
| Field | Type | Description |
|---|---|---|
status | string | Always ok on this body. |
spent | integer | Processing time in milliseconds. |
personuuid | string | The identifier of the person created by this call, or an empty string when none was. It is empty whenever person_id was sent, because an existing person was updated. |
Errors
400: The body failed validation.401: The token is missing, expired or unknown.
A refusal can also come before the operation runs: an address outside your IP allowlist, a token bound to another address, or a body that is not valid JSON. See response format and errors.
Example
Request:
curl -X POST "<API_BASE_URL>/person/fusion" \
-F "token=<your permanent API token>" \
-F "list_id=<person list id>" \
-F "embeddings=<base64 vector>" \
-F "embeddings=<base64 vector>"
Response:
{
"status": "ok",
"spent": 120,
"personuuid": "<person id>"
}