# Contacts

## Get Contact

> Get a contact by phone number or email

```json
{"openapi":"3.1.0","info":{"title":"DM Champ API","version":"1.0.0"},"servers":[{"url":"https://api.dmchamp.com/v1","description":"Production API Server"}],"security":[{"ApiKeyAuth":[]},{"UserIdAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"query","name":"apiKey","description":"Your DM Champ API key. Obtain from Settings → API Keys."},"UserIdAuth":{"type":"apiKey","in":"query","name":"userId","description":"Your DM Champ User ID. Alternative to apiKey authentication. Cannot be used for agency-only endpoints."}},"parameters":{"ApiKeyParam":{"name":"apiKey","in":"query","description":"API key for authentication. At least one of apiKey or userId is required for protected endpoints.","required":false,"schema":{"type":"string"}}}},"paths":{"/contacts":{"get":{"summary":"Get Contact","description":"Get a contact by phone number or email","tags":["Contacts"],"parameters":[{"$ref":"#/components/parameters/ApiKeyParam"},{"name":"phoneNumber","in":"query","required":false,"schema":{"type":"string"},"description":"Contact's phone number (must include valid country code)"},{"name":"email","in":"query","required":false,"schema":{"type":"string","format":"email"},"description":"Contact's email address"}],"responses":{"200":{"description":"Contact found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"contactId":{"type":"string"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"oneOf":[{"type":"string"},{"type":"object","properties":{"error":{"type":"string"}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Contact not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}}}}}}}
```

## Create New Contact

> Create a new contact with phone number and optional information.\
> \
> \*\*New Feature\*\*: You can now optionally add the contact to one or more lists upon creation.\
> \
> \*\*List Assignment Options\*\*:\
> \- Use \`listId\` for adding to a single list (simpler for single list case)\
> \- Use \`listIds\` for adding to multiple lists (array format)\
> \- If both are provided, \`listIds\` takes precedence\
> \
> The API will:\
> \- Validate that all lists exist\
> \- Verify you have permission to add contacts to each list\
> \- Create the contact and add it to the specified lists atomically\
> \
> If any list validation fails, the contact will not be created.<br>

```json
{"openapi":"3.1.0","info":{"title":"DM Champ API","version":"1.0.0"},"servers":[{"url":"https://api.dmchamp.com/v1","description":"Production API Server"}],"security":[{"ApiKeyAuth":[]},{"UserIdAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"query","name":"apiKey","description":"Your DM Champ API key. Obtain from Settings → API Keys."},"UserIdAuth":{"type":"apiKey","in":"query","name":"userId","description":"Your DM Champ User ID. Alternative to apiKey authentication. Cannot be used for agency-only endpoints."}},"parameters":{"ApiKeyParam":{"name":"apiKey","in":"query","description":"API key for authentication. At least one of apiKey or userId is required for protected endpoints.","required":false,"schema":{"type":"string"}}},"schemas":{"Contact":{"type":"object","required":["phoneNumber"],"properties":{"phoneNumber":{"type":"string","description":"Contact's phone number (must include valid country code)"},"firstName":{"type":"string","description":"Contact's first name","default":"Unknown"},"lastName":{"type":"string","description":"Contact's last name","default":"Unknown"},"email":{"type":"string","description":"Contact's email address","format":"email","default":"unknown@unknown.com"},"is_bot_active":{"type":"boolean","description":"Whether the bot is active for this contact","default":true},"listId":{"type":"string","description":"Single list ID to add the contact to upon creation"},"listIds":{"type":"array","items":{"type":"string"},"description":"Multiple list IDs to add the contact to upon creation (takes precedence over listId)"},"instagramId":{"type":["string","null"],"description":"Contact's Instagram ID"},"currentCampaign":{"type":["string","null"],"description":"Current campaign identifier"},"currentCampaignData":{"type":["object","null"],"description":"Data associated with current campaign"},"channel":{"type":["string","null"],"description":"Communication channel"},"isChatWindowOpen":{"type":"boolean","default":false,"description":"Whether chat window is open"},"externalId":{"type":["string","null"],"description":"External identifier"},"customChannel":{"type":["string","null"],"description":"Custom channel identifier"},"chatWidgetId":{"type":["string","null"],"description":"Chat widget identifier"},"do_not_disturb":{"type":"boolean","default":false,"description":"Whether the contact should not be disturbed"}}}}},"paths":{"/contacts":{"post":{"summary":"Create New Contact","description":"Create a new contact with phone number and optional information.\n\n**New Feature**: You can now optionally add the contact to one or more lists upon creation.\n\n**List Assignment Options**:\n- Use `listId` for adding to a single list (simpler for single list case)\n- Use `listIds` for adding to multiple lists (array format)\n- If both are provided, `listIds` takes precedence\n\nThe API will:\n- Validate that all lists exist\n- Verify you have permission to add contacts to each list\n- Create the contact and add it to the specified lists atomically\n\nIf any list validation fails, the contact will not be created.\n","tags":["Contacts"],"parameters":[{"$ref":"#/components/parameters/ApiKeyParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"responses":{"200":{"description":"Contact created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string"},"contactId":{"type":"string"},"listsAdded":{"type":"array","items":{"type":"string"},"description":"List IDs the contact was added to"}}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"error_code":{"type":"integer"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"error_code":{"type":"integer"}}}}}},"404":{"description":"List not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"error_code":{"type":"integer"}}}}}},"409":{"description":"Contact already exists","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"error_code":{"type":"integer"}}}}}}}}}}}
```

## Update Contact

> Update an existing contact's information

```json
{"openapi":"3.1.0","info":{"title":"DM Champ API","version":"1.0.0"},"servers":[{"url":"https://api.dmchamp.com/v1","description":"Production API Server"}],"security":[{"ApiKeyAuth":[]},{"UserIdAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"query","name":"apiKey","description":"Your DM Champ API key. Obtain from Settings → API Keys."},"UserIdAuth":{"type":"apiKey","in":"query","name":"userId","description":"Your DM Champ User ID. Alternative to apiKey authentication. Cannot be used for agency-only endpoints."}},"parameters":{"ApiKeyParam":{"name":"apiKey","in":"query","description":"API key for authentication. At least one of apiKey or userId is required for protected endpoints.","required":false,"schema":{"type":"string"}}}},"paths":{"/contacts/{contactId}":{"put":{"summary":"Update Contact","description":"Update an existing contact's information","tags":["Contacts"],"parameters":[{"$ref":"#/components/parameters/ApiKeyParam"},{"name":"contactId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the contact to update"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","description":"Contact's first name"},"lastName":{"type":"string","description":"Contact's last name"},"email":{"type":"string","description":"Contact's email address","format":"email"},"is_bot_active":{"type":"boolean","description":"Whether the bot is active for this contact"},"do_not_disturb":{"type":"boolean","description":"Whether the contact should not be disturbed"}}}}}},"responses":{"200":{"description":"Contact updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Contact not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"error_code":{"type":"integer"}}}}}}}}}}}
```

## Add Contact To List

> Add a specific contact to a list

```json
{"openapi":"3.1.0","info":{"title":"DM Champ API","version":"1.0.0"},"servers":[{"url":"https://api.dmchamp.com/v1","description":"Production API Server"}],"security":[{"ApiKeyAuth":[]},{"UserIdAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"query","name":"apiKey","description":"Your DM Champ API key. Obtain from Settings → API Keys."},"UserIdAuth":{"type":"apiKey","in":"query","name":"userId","description":"Your DM Champ User ID. Alternative to apiKey authentication. Cannot be used for agency-only endpoints."}},"parameters":{"ApiKeyParam":{"name":"apiKey","in":"query","description":"API key for authentication. At least one of apiKey or userId is required for protected endpoints.","required":false,"schema":{"type":"string"}}}},"paths":{"/contacts/lists":{"post":{"summary":"Add Contact To List","description":"Add a specific contact to a list","tags":["Contacts","Lists"],"parameters":[{"$ref":"#/components/parameters/ApiKeyParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contactId","listId"],"properties":{"contactId":{"type":"string","description":"ID of the contact to add to the list"},"listId":{"type":"string","description":"ID of the list to add the contact to"}}}}}},"responses":{"200":{"description":"Contact added to list successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"description":"Missing required parameters","content":{"application/json":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}}}}}}}
```

## Remove Contact From List

> Remove a specific contact from a list

```json
{"openapi":"3.1.0","info":{"title":"DM Champ API","version":"1.0.0"},"servers":[{"url":"https://api.dmchamp.com/v1","description":"Production API Server"}],"security":[{"ApiKeyAuth":[]},{"UserIdAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"query","name":"apiKey","description":"Your DM Champ API key. Obtain from Settings → API Keys."},"UserIdAuth":{"type":"apiKey","in":"query","name":"userId","description":"Your DM Champ User ID. Alternative to apiKey authentication. Cannot be used for agency-only endpoints."}},"parameters":{"ApiKeyParam":{"name":"apiKey","in":"query","description":"API key for authentication. At least one of apiKey or userId is required for protected endpoints.","required":false,"schema":{"type":"string"}}}},"paths":{"/contacts/lists":{"delete":{"summary":"Remove Contact From List","description":"Remove a specific contact from a list","tags":["Contacts","Lists"],"parameters":[{"$ref":"#/components/parameters/ApiKeyParam"},{"name":"contactId","in":"query","required":true,"schema":{"type":"string"},"description":"ID of the contact to remove from the list"},{"name":"listId","in":"query","required":true,"schema":{"type":"string"},"description":"ID of the list to remove the contact from"}],"responses":{"200":{"description":"Contact removed from list successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"description":"Missing required parameters","content":{"application/json":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}}}}}}}
```

## Get Contact Tags

> Get all tags associated with a contact

```json
{"openapi":"3.1.0","info":{"title":"DM Champ API","version":"1.0.0"},"servers":[{"url":"https://api.dmchamp.com/v1","description":"Production API Server"}],"security":[{"ApiKeyAuth":[]},{"UserIdAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"query","name":"apiKey","description":"Your DM Champ API key. Obtain from Settings → API Keys."},"UserIdAuth":{"type":"apiKey","in":"query","name":"userId","description":"Your DM Champ User ID. Alternative to apiKey authentication. Cannot be used for agency-only endpoints."}},"parameters":{"ApiKeyParam":{"name":"apiKey","in":"query","description":"API key for authentication. At least one of apiKey or userId is required for protected endpoints.","required":false,"schema":{"type":"string"}}},"schemas":{"Tag":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Tag name"},"description":{"type":"string","description":"Tag description"}}}}},"paths":{"/contacts/tags/{contactId}":{"get":{"summary":"Get Contact Tags","description":"Get all tags associated with a contact","tags":["Contacts","Tags"],"parameters":[{"$ref":"#/components/parameters/ApiKeyParam"},{"name":"contactId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the contact to get tags for"}],"responses":{"200":{"description":"List of contact tags","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}}}}},"400":{"description":"Missing contact ID","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}}}},"404":{"description":"Contact not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}}}}}}}}}
```

## Get Contact Messages

> Retrieve messages for a specific contact

```json
{"openapi":"3.1.0","info":{"title":"DM Champ API","version":"1.0.0"},"servers":[{"url":"https://api.dmchamp.com/v1","description":"Production API Server"}],"security":[{"ApiKeyAuth":[]},{"UserIdAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"query","name":"apiKey","description":"Your DM Champ API key. Obtain from Settings → API Keys."},"UserIdAuth":{"type":"apiKey","in":"query","name":"userId","description":"Your DM Champ User ID. Alternative to apiKey authentication. Cannot be used for agency-only endpoints."}},"parameters":{"ApiKeyParam":{"name":"apiKey","in":"query","description":"API key for authentication. At least one of apiKey or userId is required for protected endpoints.","required":false,"schema":{"type":"string"}}},"schemas":{"Message":{"type":"object","properties":{"content":{"type":"string","description":"Message content"},"timestamp":{"type":"string","format":"date-time"},"sender":{"type":"string"},"channel":{"type":"string"}}}}},"paths":{"/contacts/messages/{contactId}":{"get":{"summary":"Get Contact Messages","description":"Retrieve messages for a specific contact","tags":["Contacts","Messages"],"parameters":[{"$ref":"#/components/parameters/ApiKeyParam"},{"name":"contactId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the contact to get messages for"}],"responses":{"200":{"description":"List of messages","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}}}}}}},"400":{"description":"Missing contact ID","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}}}},"404":{"description":"Contact not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}}}}}}}}}
```