> For the complete documentation index, see [llms.txt](https://docs.agentalk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.agentalk.io/api-reference/contacts.md).

# 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."}}},"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)"}}}}}}
````

## 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."}}},"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}],"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."}}},"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}],"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."}}},"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}],"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."}}},"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}],"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."}}},"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}],"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."}}},"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"}],"tags":["Contacts"],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}},"description":"Search results"}}}}}}
````


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.