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

# Contacts

Manage contacts in your team.

## GET /contacts

> List contacts

```json
{"openapi":"3.0.3","info":{"title":"HeyGuest External API","version":"1.1.0"},"tags":[{"name":"Contacts","description":"Manage contacts in your team."}],"servers":[{"url":"https://app.heyguest.ai/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Sanctum personal access token (team-scoped)"}},"schemas":{"Pagination":{"type":"object","properties":{"links":{"type":"object","properties":{"first":{"type":"string","nullable":true},"last":{"type":"string","nullable":true},"prev":{"type":"string","nullable":true},"next":{"type":"string","nullable":true}}},"meta":{"type":"object","properties":{"current_page":{"type":"integer"},"from":{"type":"integer","nullable":true},"last_page":{"type":"integer"},"path":{"type":"string"},"per_page":{"type":"integer"},"to":{"type":"integer","nullable":true},"total":{"type":"integer"}}}}},"Contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"uuid":{"type":"string","format":"uuid"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true,"description":"Alias of phone_number."},"phone_number":{"type":"string","nullable":true},"date_of_birth":{"type":"string","format":"date","nullable":true},"email_consent":{"type":"boolean","nullable":true},"sms_consent":{"type":"boolean","nullable":true},"whatsapp_consent":{"type":"boolean","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"custom_fields":{"type":"object","description":"Keys are the slug of each custom field defined for your team; values are the stored value.\n","additionalProperties":true}}}}},"paths":{"/contacts":{"get":{"tags":["Contacts"],"summary":"List contacts","operationId":"listContacts","parameters":[{"in":"query","name":"search","schema":{"type":"string"},"description":"Substring match against first_name, last_name, email, or phone_number."},{"in":"query","name":"location_id","schema":{"type":"integer"},"description":"Filter by the contact's last_location_id."},{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"Paginated list of contacts.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Pagination"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}}}}]}}}}}}}}}
```

## Create or upsert a contact

> Creates a new contact, or updates the existing one if a contact with the\
> same email or phone\_number already exists in your team.\
> \
> Either \`email\` or \`phone\_number\` is required.<br>

```json
{"openapi":"3.0.3","info":{"title":"HeyGuest External API","version":"1.1.0"},"tags":[{"name":"Contacts","description":"Manage contacts in your team."}],"servers":[{"url":"https://app.heyguest.ai/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Sanctum personal access token (team-scoped)"}},"schemas":{"ContactWritable":{"type":"object","description":"Body for `POST /contacts` and `PATCH /contacts/{uuid}`. On create, either\n`email` or `phone_number` is required.\n","properties":{"first_name":{"type":"string","maxLength":255,"nullable":true},"last_name":{"type":"string","maxLength":255,"nullable":true},"email":{"type":"string","format":"email","maxLength":255,"nullable":true},"phone_number":{"type":"string","maxLength":255,"nullable":true,"description":"E.164 or local format; validated via `phone` rule."},"email_consent":{"type":"boolean","nullable":true},"sms_consent":{"type":"boolean","nullable":true},"whatsapp_consent":{"type":"boolean","nullable":true},"date_of_birth":{"type":"string","format":"date","nullable":true},"custom_fields":{"type":"object","description":"Map of custom field slug → value.","additionalProperties":true}}},"Contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"uuid":{"type":"string","format":"uuid"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true,"description":"Alias of phone_number."},"phone_number":{"type":"string","nullable":true},"date_of_birth":{"type":"string","format":"date","nullable":true},"email_consent":{"type":"boolean","nullable":true},"sms_consent":{"type":"boolean","nullable":true},"whatsapp_consent":{"type":"boolean","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"custom_fields":{"type":"object","description":"Keys are the slug of each custom field defined for your team; values are the stored value.\n","additionalProperties":true}}},"ValidationError":{"type":"object","properties":{"errors":{"type":"object","description":"Map of field name → array of error messages.","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/contacts":{"post":{"tags":["Contacts"],"summary":"Create or upsert a contact","description":"Creates a new contact, or updates the existing one if a contact with the\nsame email or phone_number already exists in your team.\n\nEither `email` or `phone_number` is required.\n","operationId":"createContact","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactWritable"}}}},"responses":{"200":{"description":"Contact created or updated.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"}}}}}},"422":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}}}}}
```

## GET /contacts/{uuid}

> Read a contact

```json
{"openapi":"3.0.3","info":{"title":"HeyGuest External API","version":"1.1.0"},"tags":[{"name":"Contacts","description":"Manage contacts in your team."}],"servers":[{"url":"https://app.heyguest.ai/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Sanctum personal access token (team-scoped)"}},"schemas":{"Contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"uuid":{"type":"string","format":"uuid"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true,"description":"Alias of phone_number."},"phone_number":{"type":"string","nullable":true},"date_of_birth":{"type":"string","format":"date","nullable":true},"email_consent":{"type":"boolean","nullable":true},"sms_consent":{"type":"boolean","nullable":true},"whatsapp_consent":{"type":"boolean","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"custom_fields":{"type":"object","description":"Keys are the slug of each custom field defined for your team; values are the stored value.\n","additionalProperties":true}}}}},"paths":{"/contacts/{uuid}":{"get":{"tags":["Contacts"],"summary":"Read a contact","operationId":"getContact","responses":{"200":{"description":"Contact.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"}}}}}},"404":{"description":"Contact not found in your team."}}}}}}
```

## Update a contact

> Partial update. Omitted fields are left untouched.

```json
{"openapi":"3.0.3","info":{"title":"HeyGuest External API","version":"1.1.0"},"tags":[{"name":"Contacts","description":"Manage contacts in your team."}],"servers":[{"url":"https://app.heyguest.ai/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Sanctum personal access token (team-scoped)"}},"schemas":{"ContactWritable":{"type":"object","description":"Body for `POST /contacts` and `PATCH /contacts/{uuid}`. On create, either\n`email` or `phone_number` is required.\n","properties":{"first_name":{"type":"string","maxLength":255,"nullable":true},"last_name":{"type":"string","maxLength":255,"nullable":true},"email":{"type":"string","format":"email","maxLength":255,"nullable":true},"phone_number":{"type":"string","maxLength":255,"nullable":true,"description":"E.164 or local format; validated via `phone` rule."},"email_consent":{"type":"boolean","nullable":true},"sms_consent":{"type":"boolean","nullable":true},"whatsapp_consent":{"type":"boolean","nullable":true},"date_of_birth":{"type":"string","format":"date","nullable":true},"custom_fields":{"type":"object","description":"Map of custom field slug → value.","additionalProperties":true}}},"Contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"uuid":{"type":"string","format":"uuid"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true,"description":"Alias of phone_number."},"phone_number":{"type":"string","nullable":true},"date_of_birth":{"type":"string","format":"date","nullable":true},"email_consent":{"type":"boolean","nullable":true},"sms_consent":{"type":"boolean","nullable":true},"whatsapp_consent":{"type":"boolean","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"custom_fields":{"type":"object","description":"Keys are the slug of each custom field defined for your team; values are the stored value.\n","additionalProperties":true}}},"ValidationError":{"type":"object","properties":{"errors":{"type":"object","description":"Map of field name → array of error messages.","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/contacts/{uuid}":{"patch":{"tags":["Contacts"],"summary":"Update a contact","description":"Partial update. Omitted fields are left untouched.","operationId":"updateContact","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactWritable"}}}},"responses":{"200":{"description":"Contact updated.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"}}}}}},"404":{"description":"Contact not found in your team."},"422":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}}}}}
```