Contacts
`/contacts`
One page of records, newest first unless you say otherwise, with the total count in meta so you know how far to paginate.
Required scope: contacts:read.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
page?integer1-based. meta.totalPages says how many there are.
1 <= value1per_page?integerRows per page. A value above 200 returns 400 - never a silent clamp.
1 <= value <= 20050sort?stringPrefix with - for descending. An undeclared sort returns 400.
"-createdAt""createdAt""-createdAt""name""-name"q?stringCase-insensitive "contains", across: name, email.
filter[isDecisionMaker]?stringExact match on isDecisionMaker.
"true""false"filter[lead]?stringfalse (the default) leaves out the people that only an unconverted lead knows; true lists only them. They join the directory when the lead converts.
"true""false"filter[clientId]?stringExact match on clientId.
The requested page.
application/json- response
data*array<>meta*curl -X GET 'https://api.usedashly.com/v1/contacts'{ "data": [ { "id": "string", "clientId": "string", "name": "string", "firstName": "string", "lastName": "string", "email": "string", "phone": "string", "role": "string", "linkedinUrl": "string", "isDecisionMaker": true, "createdAt": "2019-08-24T14:15:22Z", "customFields": {} } ], "meta": { "page": 0, "perPage": 0, "total": 0, "totalPages": 0 }}Links are given as the target's public id (clientId: "hsbftmp3f5"); the API resolves them server-side. Fields the database requires but the interface decides for you are filled in the same way here.
Required scope: contacts:write.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
Idempotency-Key?stringA value you choose (a UUID is the usual one), 8 to 255 characters of A-Z a-z 0-9 _ . : -. Retrying with the same key returns the first call's answer instead of creating a second record, for seven days. The same key with a different body returns 409.
8 <= length <= 255application/json- body
firstName*string1 <= length <= 80lastName?stringlength <= 80email?|nullphone?|Phone number, stored in E.164 (+33612345678). A national number is read as French; a number that is not valid for its country is refused (validation_failed).
role?|nulllinkedinUrl?|nullisDecisionMaker?booleanclientId?string|nullcreatedAt?stringWhen this actually happened, for an import. Past dates only; defaults to now. updatedAt follows it unless the body sets one.
date-timeCreated. The body is the new record, as a read would return it.
application/json- response
data*curl -X POST 'https://api.usedashly.com/v1/contacts' \ -H 'Content-Type: application/json' \ -d '{ "firstName": "string"}'{ "data": { "id": "string", "clientId": "string", "name": "string", "firstName": "string", "lastName": "string", "email": "string", "phone": "string", "role": "string", "linkedinUrl": "string", "isDecisionMaker": true, "createdAt": "2019-08-24T14:15:22Z", "customFields": {} }}The full record, custom fields included when the resource carries them. A record from another agency is a 404, not a 403 - its existence is not ours to confirm.
Required scope: contacts:read.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
id*stringThe record's public id (hsbftmp3f5), as returned in the id field. An internal UUID returns 404.
Found.
application/json- response
data*curl -X GET 'https://api.usedashly.com/v1/contacts/string'{ "data": { "id": "string", "clientId": "string", "name": "string", "firstName": "string", "lastName": "string", "email": "string", "phone": "string", "role": "string", "linkedinUrl": "string", "isDecisionMaker": true, "createdAt": "2019-08-24T14:15:22Z", "customFields": {} }}A partial update: only the fields you send change. One exception - customFields is replaced wholesale, not merged, so sending it with a single key clears the others. Read the record, merge, then write.
Required scope: contacts:write.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
id*stringThe record's public id (hsbftmp3f5), as returned in the id field. An internal UUID returns 404.
application/json- body
firstName?string1 <= length <= 80lastName?stringlength <= 80email?|nullphone?|Phone number, stored in E.164 (+33612345678). A national number is read as French; a number that is not valid for its country is refused (validation_failed).
role?|nulllinkedinUrl?|nullisDecisionMaker?booleanclientId?string|nullUpdated. The body is the record as it now stands.
application/json- response
data*curl -X PATCH 'https://api.usedashly.com/v1/contacts/string' \ -H 'Content-Type: application/json' \ -d '{}'{ "data": { "id": "string", "clientId": "string", "name": "string", "firstName": "string", "lastName": "string", "email": "string", "phone": "string", "role": "string", "linkedinUrl": "string", "isDecisionMaker": true, "createdAt": "2019-08-24T14:15:22Z", "customFields": {} }}Permanent. The audit log keeps the trace; the record does not come back.
Required scope: contacts:write.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
id*stringThe record's public id (hsbftmp3f5), as returned in the id field. An internal UUID returns 404.
Deleted. Empty body.
curl -X DELETE 'https://api.usedashly.com/v1/contacts/string'Every verb this resource answers to, with its target and the JSON Schema of its body - the same contracts this document describes, readable at runtime.
Required scope: contacts:read.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
The available verbs.
application/json- response
data*array<>curl -X GET 'https://api.usedashly.com/v1/contacts/actions'{ "data": [ { "name": "string", "label": "string", "description": "string", "target": "item", "readOnly": true, "path": "string", "input": {} } ]}Creates a relation between this record and a target object (targetType plus the target's public targetId) in the relation graph. Linking the same pair twice does nothing.
Does what the dashboard's linkObjectAction does - same implementation, so the two cannot diverge.
Required scope: contacts:write.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
id*stringThe public id of the record to act on. It is resolved inside your agency before the action runs, so an id from another tenant is a 404 and never reaches it.
Idempotency-Key?stringA value you choose (a UUID is the usual one), 8 to 255 characters of A-Z a-z 0-9 _ . : -. Retrying with the same key returns the first call's answer instead of creating a second record, for seven days. The same key with a different body returns 409.
8 <= length <= 255application/json- body
targetType*string"account""contact""project""ticket""deal""user""proposal"targetId*string1 <= length <= 60Done.
application/json- response
data*unknownThe action's result; its shape depends on the verb.
curl -X POST 'https://api.usedashly.com/v1/contacts/string/actions/link-object' \ -H 'Content-Type: application/json' \ -d '{ "targetType": "account", "targetId": "string"}'{ "data": null}Removes the relation between this record and the target object in the relation graph. Unlinking a pair that was never linked does nothing. A deal/project pair is unlinked like unlink-project on the deal: the change is audited, so the key must be attached to a user (403 with reason key_not_attached otherwise).
Does what the dashboard's unlinkObjectAction does - same implementation, so the two cannot diverge.
Required scope: contacts:write.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
id*stringThe public id of the record to act on. It is resolved inside your agency before the action runs, so an id from another tenant is a 404 and never reaches it.
Idempotency-Key?stringA value you choose (a UUID is the usual one), 8 to 255 characters of A-Z a-z 0-9 _ . : -. Retrying with the same key returns the first call's answer instead of creating a second record, for seven days. The same key with a different body returns 409.
8 <= length <= 255application/json- body
targetType*string"account""contact""project""ticket""deal""user""proposal"targetId*string1 <= length <= 60Done.
application/json- response
data*unknownThe action's result; its shape depends on the verb.
curl -X POST 'https://api.usedashly.com/v1/contacts/string/actions/unlink-object' \ -H 'Content-Type: application/json' \ -d '{ "targetType": "account", "targetId": "string"}'{ "data": null}Links this person to the given client, or updates the job title and the e-mail address they use at that organisation. The first link becomes their primary organisation.
Does what the dashboard's linkContactAccountAction does - same implementation, so the two cannot diverge.
Required scope: contacts:write.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
id*stringThe public id of the record to act on. It is resolved inside your agency before the action runs, so an id from another tenant is a 404 and never reaches it.
Idempotency-Key?stringA value you choose (a UUID is the usual one), 8 to 255 characters of A-Z a-z 0-9 _ . : -. Retrying with the same key returns the first call's answer instead of creating a second record, for seven days. The same key with a different body returns 409.
8 <= length <= 255application/json- body
clientId*string1 <= length <= 60title?stringlength <= 80email?|stringDone.
application/json- response
data*unknownThe action's result; its shape depends on the verb.
curl -X POST 'https://api.usedashly.com/v1/contacts/string/actions/link-account' \ -H 'Content-Type: application/json' \ -d '{ "clientId": "string"}'{ "data": null}Removes the link between this person and the given client. If it was their primary organisation, another link takes over.
Does what the dashboard's unlinkContactAccountAction does - same implementation, so the two cannot diverge.
Required scope: contacts:write.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
id*stringThe public id of the record to act on. It is resolved inside your agency before the action runs, so an id from another tenant is a 404 and never reaches it.
Idempotency-Key?stringA value you choose (a UUID is the usual one), 8 to 255 characters of A-Z a-z 0-9 _ . : -. Retrying with the same key returns the first call's answer instead of creating a second record, for seven days. The same key with a different body returns 409.
8 <= length <= 255application/json- body
clientId*string1 <= length <= 60Done.
application/json- response
data*unknownThe action's result; its shape depends on the verb.
curl -X POST 'https://api.usedashly.com/v1/contacts/string/actions/unlink-account' \ -H 'Content-Type: application/json' \ -d '{ "clientId": "string"}'{ "data": null}Makes the given client this person's primary organisation - the one single-company views show. The other links are kept.
Does what the dashboard's setPrimaryAccountAction does - same implementation, so the two cannot diverge.
Required scope: contacts:write.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
id*stringThe public id of the record to act on. It is resolved inside your agency before the action runs, so an id from another tenant is a 404 and never reaches it.
Idempotency-Key?stringA value you choose (a UUID is the usual one), 8 to 255 characters of A-Z a-z 0-9 _ . : -. Retrying with the same key returns the first call's answer instead of creating a second record, for seven days. The same key with a different body returns 409.
8 <= length <= 255application/json- body
clientId*string1 <= length <= 60Done.
application/json- response
data*unknownThe action's result; its shape depends on the verb.
curl -X POST 'https://api.usedashly.com/v1/contacts/string/actions/set-primary-account' \ -H 'Content-Type: application/json' \ -d '{ "clientId": "string"}'{ "data": null}Folds the given contacts into this one: its empty fields are filled from theirs, everything that named them (deals, activities, calls, organisations) now names this contact, and they are deleted. Irreversible.
Does what the dashboard's mergeContactsAction does - same implementation, so the two cannot diverge.
Required scope: contacts:write.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
id*stringThe public id of the record to act on. It is resolved inside your agency before the action runs, so an id from another tenant is a 404 and never reaches it.
Idempotency-Key?stringA value you choose (a UUID is the usual one), 8 to 255 characters of A-Z a-z 0-9 _ . : -. Retrying with the same key returns the first call's answer instead of creating a second record, for seven days. The same key with a different body returns 409.
8 <= length <= 255application/json- body
contactIds*array<>1 <= items <= 100Done.
application/json- response
data*unknownThe action's result; its shape depends on the verb.
curl -X POST 'https://api.usedashly.com/v1/contacts/string/actions/merge' \ -H 'Content-Type: application/json' \ -d '{ "contactIds": [ "string" ]}'{ "data": null}The person's latest phone exchanges (at most 20, newest first): calls with direction, status (answered, missed, voicemail), duration, recording link and the agent's note, and SMS with their text. Includes the unattached exchanges whose number is the person's in full. Read-only.
Reads the same data as the in-app listPhoneExchanges - same implementation. Changes nothing; also answers GET with the same fields as query parameters.
Required scope: contacts:read.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
id*stringThe public id of the record to act on. It is resolved inside your agency before the action runs, so an id from another tenant is a 404 and never reaches it.
The figures.
application/json- response
data*unknownThe action's result; its shape depends on the verb.
curl -X GET 'https://api.usedashly.com/v1/contacts/string/actions/phone-exchanges'{ "data": null}The person's latest phone exchanges (at most 20, newest first): calls with direction, status (answered, missed, voicemail), duration, recording link and the agent's note, and SMS with their text. Includes the unattached exchanges whose number is the person's in full. Read-only.
Reads the same data as the in-app listPhoneExchanges - same implementation. Changes nothing; also answers GET with the same fields as query parameters.
Required scope: contacts:read.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
id*stringThe public id of the record to act on. It is resolved inside your agency before the action runs, so an id from another tenant is a 404 and never reaches it.
Idempotency-Key?stringA value you choose (a UUID is the usual one), 8 to 255 characters of A-Z a-z 0-9 _ . : -. Retrying with the same key returns the first call's answer instead of creating a second record, for seven days. The same key with a different body returns 409.
8 <= length <= 255application/json- body
Done.
application/json- response
data*unknownThe action's result; its shape depends on the verb.
curl -X POST 'https://api.usedashly.com/v1/contacts/string/actions/phone-exchanges' \ -H 'Content-Type: application/json' \ -d '{}'{ "data": null}Stores the person's picture as a data URI (PNG, JPEG or WebP, already resized). null removes it.
Does what the dashboard's setContactAvatarAction does - same implementation, so the two cannot diverge.
Required scope: contacts:write.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
id*stringThe public id of the record to act on. It is resolved inside your agency before the action runs, so an id from another tenant is a 404 and never reaches it.
Idempotency-Key?stringA value you choose (a UUID is the usual one), 8 to 255 characters of A-Z a-z 0-9 _ . : -. Retrying with the same key returns the first call's answer instead of creating a second record, for seven days. The same key with a different body returns 409.
8 <= length <= 255application/json- body
avatar*|nullDone.
application/json- response
data*unknownThe action's result; its shape depends on the verb.
curl -X POST 'https://api.usedashly.com/v1/contacts/string/actions/set-avatar' \ -H 'Content-Type: application/json' \ -d '{ "avatar": "string"}'{ "data": null}