# Contacts

Create, update, search, and manage contacts

## Create or Update Contact

> Create a new contact or update an existing one. If a contact with the same phone number exists, it will be updated.

````json
{"openapi":"3.0.3","info":{"title":"Agentalk External API","version":"1.0.0"},"tags":[{"name":"Contacts","description":"Create, update, search, and manage contacts"}],"servers":[{"url":"https://api.agentalk.io","description":"Agentalk API"}],"security":[{"OrganizationApiToken":[]}],"components":{"securitySchemes":{"OrganizationApiToken":{"type":"http","scheme":"bearer","bearerFormat":"OrgId.SecretToken","description":"**Organization API Token.**\n\nPaste **only** your token in the field below — the `Bearer ` prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:\n\n```\nAuthorization: Bearer {orgId}.{secretToken}\n```\n\nToken format: `{orgId}.{secretToken}` — example: `15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz`.\n\nJWT tokens are NOT accepted."}},"parameters":{"XOrganizationId":{"name":"X-Organization-ID","in":"header","required":false,"description":"Optional organization scope. Superusers without it see all; regular users default to their current organization.","schema":{"type":"string","format":"uuid"}}}},"paths":{"/api/contacts":{"post":{"operationId":"contacts_create","description":"Create a new contact or update an existing one. If a contact with the same phone number exists, it will be updated.","summary":"Create or Update Contact","tags":["Contacts"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"type":"string","description":"Phone number with country code (required)"},"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"email":{"type":"string","format":"email","description":"Email address"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags to assign"},"fields":{"type":"object","description":"Fields to create/update"}},"required":["phone"]}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}},"description":"Contact updated (isNew: false)"},"201":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}},"description":"Contact created (isNew: true)"}},"parameters":[{"$ref":"#/components/parameters/XOrganizationId"}]}}}}
````

## Delete Contact

> Permanently delete a contact by ID.

````json
{"openapi":"3.0.3","info":{"title":"Agentalk External API","version":"1.0.0"},"tags":[{"name":"Contacts","description":"Create, update, search, and manage contacts"}],"servers":[{"url":"https://api.agentalk.io","description":"Agentalk API"}],"security":[{"OrganizationApiToken":[]}],"components":{"securitySchemes":{"OrganizationApiToken":{"type":"http","scheme":"bearer","bearerFormat":"OrgId.SecretToken","description":"**Organization API Token.**\n\nPaste **only** your token in the field below — the `Bearer ` prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:\n\n```\nAuthorization: Bearer {orgId}.{secretToken}\n```\n\nToken format: `{orgId}.{secretToken}` — example: `15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz`.\n\nJWT tokens are NOT accepted."}},"parameters":{"XOrganizationId":{"name":"X-Organization-ID","in":"header","required":false,"description":"Optional organization scope. Superusers without it see all; regular users default to their current organization.","schema":{"type":"string","format":"uuid"}}}},"paths":{"/api/contacts/{contact_id}":{"delete":{"operationId":"contacts_destroy","description":"Permanently delete a contact by ID.","summary":"Delete Contact","parameters":[{"in":"path","name":"contact_id","schema":{"type":"string","format":"uuid"},"description":"Contact ID","required":true},{"$ref":"#/components/parameters/XOrganizationId"}],"tags":["Contacts"],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}},"description":"Contact deleted"}}}}}}
````

## Update Contact Fields

> Update one or more fields for a specific contact.

````json
{"openapi":"3.0.3","info":{"title":"Agentalk External API","version":"1.0.0"},"tags":[{"name":"Contacts","description":"Create, update, search, and manage contacts"}],"servers":[{"url":"https://api.agentalk.io","description":"Agentalk API"}],"security":[{"OrganizationApiToken":[]}],"components":{"securitySchemes":{"OrganizationApiToken":{"type":"http","scheme":"bearer","bearerFormat":"OrgId.SecretToken","description":"**Organization API Token.**\n\nPaste **only** your token in the field below — the `Bearer ` prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:\n\n```\nAuthorization: Bearer {orgId}.{secretToken}\n```\n\nToken format: `{orgId}.{secretToken}` — example: `15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz`.\n\nJWT tokens are NOT accepted."}},"parameters":{"XOrganizationId":{"name":"X-Organization-ID","in":"header","required":false,"description":"Optional organization scope. Superusers without it see all; regular users default to their current organization.","schema":{"type":"string","format":"uuid"}}}},"paths":{"/api/contacts/{contact_id}/fields":{"patch":{"operationId":"contacts_fields_partial_update","description":"Update one or more fields for a specific contact.","summary":"Update Contact Fields","parameters":[{"in":"path","name":"contact_id","schema":{"type":"string","format":"uuid"},"description":"Contact ID","required":true},{"$ref":"#/components/parameters/XOrganizationId"}],"tags":["Contacts"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fields":{"type":"object","description":"Fields to update"}},"required":["fields"]}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}},"description":"Contact updated successfully"}}}}}}
````

## Clear Contact Field

> Clear a specific field value for a contact.

````json
{"openapi":"3.0.3","info":{"title":"Agentalk External API","version":"1.0.0"},"tags":[{"name":"Contacts","description":"Create, update, search, and manage contacts"}],"servers":[{"url":"https://api.agentalk.io","description":"Agentalk API"}],"security":[{"OrganizationApiToken":[]}],"components":{"securitySchemes":{"OrganizationApiToken":{"type":"http","scheme":"bearer","bearerFormat":"OrgId.SecretToken","description":"**Organization API Token.**\n\nPaste **only** your token in the field below — the `Bearer ` prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:\n\n```\nAuthorization: Bearer {orgId}.{secretToken}\n```\n\nToken format: `{orgId}.{secretToken}` — example: `15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz`.\n\nJWT tokens are NOT accepted."}},"parameters":{"XOrganizationId":{"name":"X-Organization-ID","in":"header","required":false,"description":"Optional organization scope. Superusers without it see all; regular users default to their current organization.","schema":{"type":"string","format":"uuid"}}}},"paths":{"/api/contacts/{contact_id}/fields/{field_key}":{"delete":{"operationId":"contacts_fields_destroy","description":"Clear a specific field value for a contact.","summary":"Clear Contact Field","parameters":[{"in":"path","name":"contact_id","schema":{"type":"string","format":"uuid"},"description":"Contact ID","required":true},{"in":"path","name":"field_key","schema":{"type":"string"},"description":"Field key to clear (e.g., 'email' or 'city')","required":true},{"$ref":"#/components/parameters/XOrganizationId"}],"tags":["Contacts"],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}},"description":"Field cleared successfully"}}}}}}
````

## Add Tags to Contact

> Add one or more tags to an existing contact without replacing existing tags.

````json
{"openapi":"3.0.3","info":{"title":"Agentalk External API","version":"1.0.0"},"tags":[{"name":"Contacts","description":"Create, update, search, and manage contacts"}],"servers":[{"url":"https://api.agentalk.io","description":"Agentalk API"}],"security":[{"OrganizationApiToken":[]}],"components":{"securitySchemes":{"OrganizationApiToken":{"type":"http","scheme":"bearer","bearerFormat":"OrgId.SecretToken","description":"**Organization API Token.**\n\nPaste **only** your token in the field below — the `Bearer ` prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:\n\n```\nAuthorization: Bearer {orgId}.{secretToken}\n```\n\nToken format: `{orgId}.{secretToken}` — example: `15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz`.\n\nJWT tokens are NOT accepted."}},"parameters":{"XOrganizationId":{"name":"X-Organization-ID","in":"header","required":false,"description":"Optional organization scope. Superusers without it see all; regular users default to their current organization.","schema":{"type":"string","format":"uuid"}}}},"paths":{"/api/contacts/{contact_id}/tags":{"post":{"operationId":"contacts_tags_create","description":"Add one or more tags to an existing contact without replacing existing tags.","summary":"Add Tags to Contact","parameters":[{"in":"path","name":"contact_id","schema":{"type":"string","format":"uuid"},"description":"Contact ID","required":true},{"$ref":"#/components/parameters/XOrganizationId"}],"tags":["Contacts"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"},"description":"Tags to add"}},"required":["tags"]}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}},"description":"Tags added successfully"}}}}}}
````

## Remove Tag from Contact

> Remove a specific tag from a contact. You can use the tag ID or tag name.

````json
{"openapi":"3.0.3","info":{"title":"Agentalk External API","version":"1.0.0"},"tags":[{"name":"Contacts","description":"Create, update, search, and manage contacts"}],"servers":[{"url":"https://api.agentalk.io","description":"Agentalk API"}],"security":[{"OrganizationApiToken":[]}],"components":{"securitySchemes":{"OrganizationApiToken":{"type":"http","scheme":"bearer","bearerFormat":"OrgId.SecretToken","description":"**Organization API Token.**\n\nPaste **only** your token in the field below — the `Bearer ` prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:\n\n```\nAuthorization: Bearer {orgId}.{secretToken}\n```\n\nToken format: `{orgId}.{secretToken}` — example: `15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz`.\n\nJWT tokens are NOT accepted."}},"parameters":{"XOrganizationId":{"name":"X-Organization-ID","in":"header","required":false,"description":"Optional organization scope. Superusers without it see all; regular users default to their current organization.","schema":{"type":"string","format":"uuid"}}}},"paths":{"/api/contacts/{contact_id}/tags/{tag_id_or_name}":{"delete":{"operationId":"contacts_tags_destroy","description":"Remove a specific tag from a contact. You can use the tag ID or tag name.","summary":"Remove Tag from Contact","parameters":[{"in":"path","name":"contact_id","schema":{"type":"string","format":"uuid"},"description":"Contact ID","required":true},{"in":"path","name":"tag_id_or_name","schema":{"type":"string"},"description":"Tag ID or tag name to remove","required":true},{"$ref":"#/components/parameters/XOrganizationId"}],"tags":["Contacts"],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}},"description":"Tag removed successfully"}}}}}}
````

## Search Contacts

> Search contacts by phone number or name. At least one search parameter is required.

````json
{"openapi":"3.0.3","info":{"title":"Agentalk External API","version":"1.0.0"},"tags":[{"name":"Contacts","description":"Create, update, search, and manage contacts"}],"servers":[{"url":"https://api.agentalk.io","description":"Agentalk API"}],"security":[{"OrganizationApiToken":[]}],"components":{"securitySchemes":{"OrganizationApiToken":{"type":"http","scheme":"bearer","bearerFormat":"OrgId.SecretToken","description":"**Organization API Token.**\n\nPaste **only** your token in the field below — the `Bearer ` prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:\n\n```\nAuthorization: Bearer {orgId}.{secretToken}\n```\n\nToken format: `{orgId}.{secretToken}` — example: `15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz`.\n\nJWT tokens are NOT accepted."}},"parameters":{"XOrganizationId":{"name":"X-Organization-ID","in":"header","required":false,"description":"Optional organization scope. Superusers without it see all; regular users default to their current organization.","schema":{"type":"string","format":"uuid"}}}},"paths":{"/api/contacts/search":{"get":{"operationId":"contacts_search_retrieve","description":"Search contacts by phone number or name. At least one search parameter is required.","summary":"Search Contacts","parameters":[{"in":"query","name":"limit","schema":{"type":"integer"},"description":"Number of results to return (default: 50)"},{"in":"query","name":"name","schema":{"type":"string"},"description":"Name to search (first or last)"},{"in":"query","name":"offset","schema":{"type":"integer"},"description":"Offset for pagination (default: 0)"},{"in":"query","name":"phone","schema":{"type":"string"},"description":"Phone number to search"},{"$ref":"#/components/parameters/XOrganizationId"}],"tags":["Contacts"],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}},"description":"Search results"}}}}}}
````


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.agentalk.io/api-reference/contacts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.