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

# Contacts

## List contacts

> Returns the contacts in your organization, newest first. Each contact includes the company they work at. To get all of a contact's companies and channels, retrieve the contact.

```json
{"openapi":"3.1.0","info":{"title":"rvmpd API","version":"1.0.0"},"servers":[{"url":"https://api.rvmpd.com"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key. Create one in the dashboard under Settings, then API keys. Each key belongs to one organization, and every request made with it reads and writes that organization's data."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","rate_limit_error","api_error"],"description":"A broad category of the error. Use code for specific handling."},"code":{"type":"string","enum":["invalid_request","unauthorized","forbidden","not_found","conflict","unprocessable","rate_limited","internal_error"],"description":"invalid_request: the request is malformed or a field is invalid. unauthorized: the credentials are missing or wrong. forbidden: the credentials are valid but cannot do this. not_found: the record does not exist, or belongs to another organization. conflict: the request clashes with existing data, such as a duplicate. unprocessable: the request is well formed but a value cannot be used, such as a phone number that is not real. rate_limited: too many requests. Wait and retry. internal_error: something went wrong on our side. Retry, and contact support with the request_id if it persists."},"message":{"type":"string","description":"A sentence for a person to read. Do not parse it; it may change."},"param":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The request field the error is about, such as channels[1].value. Null when the error is not about one field."},"request_id":{"type":"string","description":"Identifies this request. Include it when contacting support."},"duplicates":{"description":"Only on a 409 conflict from creating a contact or adding a channel. Lists the existing records that may be duplicates.","type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"contact"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The existing contact's id."},"name":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The existing contact's job title."},"confidence":{"type":"string","enum":["exact","possible"],"description":"exact: the record shares an identifier, email, phone, LinkedIn profile or company domain with your request. possible: only the name is the same or similar."},"match":{"type":"object","properties":{"on":{"type":"string","enum":["identifier","email","phone","linkedin","domain","name"],"description":"What matched: an identifier such as a CRD, a channel, a company domain, or a name."},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The value that matched, such as the email address or the identifier with its scheme. Null when the match is on a name."}},"required":["on","value"],"additionalProperties":false,"description":"Why this record was matched."},"companies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"relationship":{"type":"string","description":"What the contact is at this company, such as employee or owner."},"is_primary":{"type":"boolean","description":"True for the company the contact works at."}},"required":["id","name","relationship","is_primary"],"additionalProperties":false},"description":"The companies the existing contact is connected to, to help tell people apart."}},"required":["object","id","name","title","confidence","match","companies"],"additionalProperties":false,"description":"An existing contact that may be the same person."},"description":"Existing contacts that may be the same person. Exact matches come first."},"companies":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"company"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The existing company's id. To connect a contact to it, send it as company.id."},"name":{"type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}]},"confidence":{"type":"string","enum":["exact","possible"],"description":"exact: the record shares an identifier, email, phone, LinkedIn profile or company domain with your request. possible: only the name is the same or similar."},"match":{"type":"object","properties":{"on":{"type":"string","enum":["identifier","email","phone","linkedin","domain","name"],"description":"What matched: an identifier such as a CRD, a channel, a company domain, or a name."},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The value that matched, such as the email address or the identifier with its scheme. Null when the match is on a name."}},"required":["on","value"],"additionalProperties":false,"description":"Why this record was matched."}},"required":["object","id","name","domain","confidence","match"],"additionalProperties":false,"description":"An existing company that may be the same company."},"description":"Existing companies that may be the same company. Only present when the request would create a company."}},"required":["contacts","companies"],"additionalProperties":false}},"required":["type","code","message","param","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"description":"Every error response has this shape."}}},"paths":{"/v1/contacts":{"get":{"operationId":"contacts.list","summary":"List contacts","description":"Returns the contacts in your organization, newest first. Each contact includes the company they work at. To get all of a contact's companies and channels, retrieve the contact.","tags":["Contacts"],"parameters":[{"name":"search","in":"query","required":false,"description":"Only return contacts whose name matches this text.","schema":{"description":"Only return contacts whose name matches this text.","type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","required":false,"description":"How many contacts to return, from 1 to 100. Defaults to 25.","schema":{"default":25,"description":"How many contacts to return, from 1 to 100. Defaults to 25.","type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"The next_cursor value from the previous page. Treat it as opaque.","schema":{"description":"The next_cursor value from the previous page. Treat it as opaque.","type":"string","maxLength":200}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"contact"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The contact's job title."},"address":{"type":"object","properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}]},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false},"owner_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The team member this contact is assigned to."},"relationship":{"type":"object","properties":{"status":{"type":"string","enum":["active","churned"],"description":"churned when your organization's relationship with this person has ended."},"first_engaged_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When your organization first reached this person. Null if never."},"churned_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When the relationship ended. Null unless churned."},"churn_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Why the relationship ended. Null unless churned."}},"required":["status","first_engaged_at","churned_at","churn_reason"],"additionalProperties":false,"description":"Your organization's relationship with this person."},"company":{"anyOf":[{"type":"object","properties":{"object":{"type":"string","const":"company"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}]},"relationship":{"type":"string","enum":["employee","advisor","executive","owner","board_member","registered_rep","affiliate","recruiter","consultant"],"description":"What the contact is at this company."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The contact's job title at this company."}},"required":["object","id","name","domain","relationship","title"],"additionalProperties":false,"description":"A company the contact is connected to."},{"type":"null"}],"description":"The company the contact works at. Null when none is recorded, including when the contact has companies but none is marked primary."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["object","id","name","title","address","owner_id","relationship","company","created_at","updated_at"],"additionalProperties":false,"description":"A contact as it appears in a list. Retrieve the contact to get all of its companies and channels."}},"has_more":{"type":"boolean","description":"True when there are more results after this page."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass this as cursor to get the next page. Null when there are no more results."}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Create a contact

> Creates a contact with their channels and, optionally, the company they work at. Connect an existing company by id, or create a new one by name. The request is refused with 422 if a channel value is not valid, and with 409 if the contact or company may already exist: a shared email, phone, LinkedIn profile, identifier or domain, or a similar name. A 409 lists the matches in error.duplicates. Use one of them, or send the request again with force set to true.

```json
{"openapi":"3.1.0","info":{"title":"rvmpd API","version":"1.0.0"},"servers":[{"url":"https://api.rvmpd.com"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key. Create one in the dashboard under Settings, then API keys. Each key belongs to one organization, and every request made with it reads and writes that organization's data."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","rate_limit_error","api_error"],"description":"A broad category of the error. Use code for specific handling."},"code":{"type":"string","enum":["invalid_request","unauthorized","forbidden","not_found","conflict","unprocessable","rate_limited","internal_error"],"description":"invalid_request: the request is malformed or a field is invalid. unauthorized: the credentials are missing or wrong. forbidden: the credentials are valid but cannot do this. not_found: the record does not exist, or belongs to another organization. conflict: the request clashes with existing data, such as a duplicate. unprocessable: the request is well formed but a value cannot be used, such as a phone number that is not real. rate_limited: too many requests. Wait and retry. internal_error: something went wrong on our side. Retry, and contact support with the request_id if it persists."},"message":{"type":"string","description":"A sentence for a person to read. Do not parse it; it may change."},"param":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The request field the error is about, such as channels[1].value. Null when the error is not about one field."},"request_id":{"type":"string","description":"Identifies this request. Include it when contacting support."},"duplicates":{"description":"Only on a 409 conflict from creating a contact or adding a channel. Lists the existing records that may be duplicates.","type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"contact"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The existing contact's id."},"name":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The existing contact's job title."},"confidence":{"type":"string","enum":["exact","possible"],"description":"exact: the record shares an identifier, email, phone, LinkedIn profile or company domain with your request. possible: only the name is the same or similar."},"match":{"type":"object","properties":{"on":{"type":"string","enum":["identifier","email","phone","linkedin","domain","name"],"description":"What matched: an identifier such as a CRD, a channel, a company domain, or a name."},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The value that matched, such as the email address or the identifier with its scheme. Null when the match is on a name."}},"required":["on","value"],"additionalProperties":false,"description":"Why this record was matched."},"companies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"relationship":{"type":"string","description":"What the contact is at this company, such as employee or owner."},"is_primary":{"type":"boolean","description":"True for the company the contact works at."}},"required":["id","name","relationship","is_primary"],"additionalProperties":false},"description":"The companies the existing contact is connected to, to help tell people apart."}},"required":["object","id","name","title","confidence","match","companies"],"additionalProperties":false,"description":"An existing contact that may be the same person."},"description":"Existing contacts that may be the same person. Exact matches come first."},"companies":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"company"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The existing company's id. To connect a contact to it, send it as company.id."},"name":{"type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}]},"confidence":{"type":"string","enum":["exact","possible"],"description":"exact: the record shares an identifier, email, phone, LinkedIn profile or company domain with your request. possible: only the name is the same or similar."},"match":{"type":"object","properties":{"on":{"type":"string","enum":["identifier","email","phone","linkedin","domain","name"],"description":"What matched: an identifier such as a CRD, a channel, a company domain, or a name."},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The value that matched, such as the email address or the identifier with its scheme. Null when the match is on a name."}},"required":["on","value"],"additionalProperties":false,"description":"Why this record was matched."}},"required":["object","id","name","domain","confidence","match"],"additionalProperties":false,"description":"An existing company that may be the same company."},"description":"Existing companies that may be the same company. Only present when the request would create a company."}},"required":["contacts","companies"],"additionalProperties":false}},"required":["type","code","message","param","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"description":"Every error response has this shape."}}},"paths":{"/v1/contacts":{"post":{"operationId":"contacts.create","summary":"Create a contact","description":"Creates a contact with their channels and, optionally, the company they work at. Connect an existing company by id, or create a new one by name. The request is refused with 422 if a channel value is not valid, and with 409 if the contact or company may already exist: a shared email, phone, LinkedIn profile, identifier or domain, or a similar name. A 409 lists the matches in error.duplicates. Use one of them, or send the request again with force set to true.","tags":["Contacts"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"The contact's full name."},"title":{"description":"The contact's job title.","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"address":{"type":"object","properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}]},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"channels":{"description":"The contact's emails, phone numbers and LinkedIn profile. Up to 25.","maxItems":25,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["email","phone","linkedin"],"description":"The kind of channel: email, phone or linkedin."},"value":{"type":"string","minLength":1,"maxLength":2048,"description":"The email, phone number or LinkedIn URL."},"label":{"description":"A free text label, such as Work or Mobile.","anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"is_primary":{"description":"Make this the primary channel of its type. When left out, the first channel of each type becomes primary.","type":"boolean"},"country":{"description":"Two-letter country code (ISO 3166), such as US or GB. Used only for phone numbers written without a country code. Defaults to US. A number that starts with + already names its country, so this is ignored for it.","type":"string","pattern":"^[A-Za-z]{2}$"}},"required":["type","value"],"additionalProperties":false}},"company":{"description":"The company the contact works at. It becomes their primary company.","anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The id of an existing company to connect the contact to."}},"required":["id"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"The name of a new company to create and connect the contact to."},"domain":{"description":"The company's web domain, such as acme.com.","anyOf":[{"type":"string","maxLength":253},{"type":"null"}]},"website":{"description":"The company's website URL.","anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"linkedin_url":{"description":"The company's LinkedIn page.","anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]}},"required":["name"],"additionalProperties":false}]},"company_relationship":{"description":"What the contact is at the company. Defaults to employee. Ignored when no company is given.","type":"string","enum":["employee","advisor","executive","owner","board_member","registered_rep","affiliate","recruiter","consultant"]},"force":{"description":"Create the contact even when a similar contact or company already exists. Without this, the request is refused with 409 and the matches are listed in error.duplicates.","type":"boolean"}},"required":["name"],"additionalProperties":false,"description":"A contact to create. Refused with 409 when it may be a duplicate of an existing contact or company, unless force is true. Refused with 422 when a channel value is not valid."}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"contact"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The contact's job title."},"address":{"type":"object","properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}]},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false},"owner_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The team member this contact is assigned to."},"relationship":{"type":"object","properties":{"status":{"type":"string","enum":["active","churned"],"description":"churned when your organization's relationship with this person has ended."},"first_engaged_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When your organization first reached this person. Null if never."},"churned_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When the relationship ended. Null unless churned."},"churn_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Why the relationship ended. Null unless churned."}},"required":["status","first_engaged_at","churned_at","churn_reason"],"additionalProperties":false,"description":"Your organization's relationship with this person."},"company":{"anyOf":[{"type":"object","properties":{"object":{"type":"string","const":"company"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}]},"relationship":{"type":"string","enum":["employee","advisor","executive","owner","board_member","registered_rep","affiliate","recruiter","consultant"],"description":"What the contact is at this company."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The contact's job title at this company."}},"required":["object","id","name","domain","relationship","title"],"additionalProperties":false,"description":"A company the contact is connected to."},{"type":"null"}],"description":"The company the contact works at. Null when none is recorded, including when the contact has companies but none is marked primary."},"companies":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"company"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}]},"relationship":{"type":"string","enum":["employee","advisor","executive","owner","board_member","registered_rep","affiliate","recruiter","consultant"],"description":"What the contact is at this company."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The contact's job title at this company."},"is_primary":{"type":"boolean","description":"True for the company the contact works at. A contact has at most one."}},"required":["object","id","name","domain","relationship","title","is_primary"],"additionalProperties":false,"description":"A company the contact is currently connected to."},"description":"Every company the contact is currently connected to, with the primary first."},"channels":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"channel"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["email","phone","linkedin"],"description":"The kind of channel: email, phone or linkedin."},"value":{"type":"string","description":"The value to show. Phone numbers are in international format, such as +16172531000. Emails and LinkedIn URLs are shown as entered."},"normalized":{"type":"string","description":"The form used to compare channels. Phones are in international format, emails are lowercase, and LinkedIn URLs are reduced to the host and path. Two channels of the same type are the same channel when this matches."},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A free text label, such as Work or Mobile."},"is_primary":{"type":"boolean","description":"The contact's main channel of this type. A contact has at most one per type."},"active":{"type":"boolean","description":"False when the channel has been deactivated. Deactivated channels are kept but not used."},"source":{"type":"string","enum":["manual","api","enrichment","inbound"],"description":"Where the channel came from. manual: added by your team. api: added through the API. enrichment: found by rvmpd research. inbound: the contact wrote to you from it."},"editable":{"type":"boolean","description":"False for channels found by rvmpd research. Those can be made primary, deactivated or activated, but their value and label cannot be changed and they cannot be deleted."},"verified":{"type":"boolean","description":"True when the value has passed a verification check."},"verified_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When the last verification check passed."}},"required":["object","id","type","value","normalized","label","is_primary","active","source","editable","verified","verified_at"],"additionalProperties":false,"description":"A way to reach a contact."},"description":"The contact's active channels, with each type's primary first."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["object","id","name","title","address","owner_id","relationship","company","companies","channels","created_at","updated_at"],"additionalProperties":false,"description":"A person your organization keeps a record for."}}}},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Find contacts by email, phone or LinkedIn

> Returns the contacts that have this email, phone number or LinkedIn profile. Any common format works. URL-encode the value, so a + in an email is sent as %2B. The result is a list, because a shared inbox or office line can belong to several people. It is empty when no contact has the value.

```json
{"openapi":"3.1.0","info":{"title":"rvmpd API","version":"1.0.0"},"servers":[{"url":"https://api.rvmpd.com"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key. Create one in the dashboard under Settings, then API keys. Each key belongs to one organization, and every request made with it reads and writes that organization's data."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","rate_limit_error","api_error"],"description":"A broad category of the error. Use code for specific handling."},"code":{"type":"string","enum":["invalid_request","unauthorized","forbidden","not_found","conflict","unprocessable","rate_limited","internal_error"],"description":"invalid_request: the request is malformed or a field is invalid. unauthorized: the credentials are missing or wrong. forbidden: the credentials are valid but cannot do this. not_found: the record does not exist, or belongs to another organization. conflict: the request clashes with existing data, such as a duplicate. unprocessable: the request is well formed but a value cannot be used, such as a phone number that is not real. rate_limited: too many requests. Wait and retry. internal_error: something went wrong on our side. Retry, and contact support with the request_id if it persists."},"message":{"type":"string","description":"A sentence for a person to read. Do not parse it; it may change."},"param":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The request field the error is about, such as channels[1].value. Null when the error is not about one field."},"request_id":{"type":"string","description":"Identifies this request. Include it when contacting support."},"duplicates":{"description":"Only on a 409 conflict from creating a contact or adding a channel. Lists the existing records that may be duplicates.","type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"contact"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The existing contact's id."},"name":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The existing contact's job title."},"confidence":{"type":"string","enum":["exact","possible"],"description":"exact: the record shares an identifier, email, phone, LinkedIn profile or company domain with your request. possible: only the name is the same or similar."},"match":{"type":"object","properties":{"on":{"type":"string","enum":["identifier","email","phone","linkedin","domain","name"],"description":"What matched: an identifier such as a CRD, a channel, a company domain, or a name."},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The value that matched, such as the email address or the identifier with its scheme. Null when the match is on a name."}},"required":["on","value"],"additionalProperties":false,"description":"Why this record was matched."},"companies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"relationship":{"type":"string","description":"What the contact is at this company, such as employee or owner."},"is_primary":{"type":"boolean","description":"True for the company the contact works at."}},"required":["id","name","relationship","is_primary"],"additionalProperties":false},"description":"The companies the existing contact is connected to, to help tell people apart."}},"required":["object","id","name","title","confidence","match","companies"],"additionalProperties":false,"description":"An existing contact that may be the same person."},"description":"Existing contacts that may be the same person. Exact matches come first."},"companies":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"company"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The existing company's id. To connect a contact to it, send it as company.id."},"name":{"type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}]},"confidence":{"type":"string","enum":["exact","possible"],"description":"exact: the record shares an identifier, email, phone, LinkedIn profile or company domain with your request. possible: only the name is the same or similar."},"match":{"type":"object","properties":{"on":{"type":"string","enum":["identifier","email","phone","linkedin","domain","name"],"description":"What matched: an identifier such as a CRD, a channel, a company domain, or a name."},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The value that matched, such as the email address or the identifier with its scheme. Null when the match is on a name."}},"required":["on","value"],"additionalProperties":false,"description":"Why this record was matched."}},"required":["object","id","name","domain","confidence","match"],"additionalProperties":false,"description":"An existing company that may be the same company."},"description":"Existing companies that may be the same company. Only present when the request would create a company."}},"required":["contacts","companies"],"additionalProperties":false}},"required":["type","code","message","param","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"description":"Every error response has this shape."}}},"paths":{"/v1/contacts/lookup":{"get":{"operationId":"contacts.lookup","summary":"Find contacts by email, phone or LinkedIn","description":"Returns the contacts that have this email, phone number or LinkedIn profile. Any common format works. URL-encode the value, so a + in an email is sent as %2B. The result is a list, because a shared inbox or office line can belong to several people. It is empty when no contact has the value.","tags":["Contacts"],"parameters":[{"name":"type","in":"query","required":true,"description":"The kind of channel: email, phone or linkedin.","schema":{"type":"string","enum":["email","phone","linkedin"],"description":"The kind of channel: email, phone or linkedin."}},{"name":"value","in":"query","required":true,"description":"The email, phone number or LinkedIn URL to look for, in any common format. URL-encode it: a + in an email must be sent as %2B. Case, spacing and phone punctuation do not matter.","schema":{"type":"string","minLength":1,"maxLength":2048,"description":"The email, phone number or LinkedIn URL to look for, in any common format. URL-encode it: a + in an email must be sent as %2B. Case, spacing and phone punctuation do not matter."}},{"name":"country","in":"query","required":false,"description":"Two-letter country code (ISO 3166), such as US or GB. Used only for phone numbers written without a country code. Defaults to US. A number that starts with + already names its country, so this is ignored for it.","schema":{"description":"Two-letter country code (ISO 3166), such as US or GB. Used only for phone numbers written without a country code. Defaults to US. A number that starts with + already names its country, so this is ignored for it.","type":"string","pattern":"^[A-Za-z]{2}$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"contact"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The contact's job title."},"address":{"type":"object","properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}]},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false},"owner_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The team member this contact is assigned to."},"relationship":{"type":"object","properties":{"status":{"type":"string","enum":["active","churned"],"description":"churned when your organization's relationship with this person has ended."},"first_engaged_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When your organization first reached this person. Null if never."},"churned_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When the relationship ended. Null unless churned."},"churn_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Why the relationship ended. Null unless churned."}},"required":["status","first_engaged_at","churned_at","churn_reason"],"additionalProperties":false,"description":"Your organization's relationship with this person."},"company":{"anyOf":[{"type":"object","properties":{"object":{"type":"string","const":"company"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}]},"relationship":{"type":"string","enum":["employee","advisor","executive","owner","board_member","registered_rep","affiliate","recruiter","consultant"],"description":"What the contact is at this company."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The contact's job title at this company."}},"required":["object","id","name","domain","relationship","title"],"additionalProperties":false,"description":"A company the contact is connected to."},{"type":"null"}],"description":"The company the contact works at. Null when none is recorded, including when the contact has companies but none is marked primary."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["object","id","name","title","address","owner_id","relationship","company","created_at","updated_at"],"additionalProperties":false,"description":"A contact as it appears in a list. Retrieve the contact to get all of its companies and channels."}},"has_more":{"type":"boolean","description":"True when there are more results after this page."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass this as cursor to get the next page. Null when there are no more results."}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Retrieve a contact

> Returns a contact with every company they are currently connected to and every active channel.

```json
{"openapi":"3.1.0","info":{"title":"rvmpd API","version":"1.0.0"},"servers":[{"url":"https://api.rvmpd.com"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key. Create one in the dashboard under Settings, then API keys. Each key belongs to one organization, and every request made with it reads and writes that organization's data."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","rate_limit_error","api_error"],"description":"A broad category of the error. Use code for specific handling."},"code":{"type":"string","enum":["invalid_request","unauthorized","forbidden","not_found","conflict","unprocessable","rate_limited","internal_error"],"description":"invalid_request: the request is malformed or a field is invalid. unauthorized: the credentials are missing or wrong. forbidden: the credentials are valid but cannot do this. not_found: the record does not exist, or belongs to another organization. conflict: the request clashes with existing data, such as a duplicate. unprocessable: the request is well formed but a value cannot be used, such as a phone number that is not real. rate_limited: too many requests. Wait and retry. internal_error: something went wrong on our side. Retry, and contact support with the request_id if it persists."},"message":{"type":"string","description":"A sentence for a person to read. Do not parse it; it may change."},"param":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The request field the error is about, such as channels[1].value. Null when the error is not about one field."},"request_id":{"type":"string","description":"Identifies this request. Include it when contacting support."},"duplicates":{"description":"Only on a 409 conflict from creating a contact or adding a channel. Lists the existing records that may be duplicates.","type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"contact"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The existing contact's id."},"name":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The existing contact's job title."},"confidence":{"type":"string","enum":["exact","possible"],"description":"exact: the record shares an identifier, email, phone, LinkedIn profile or company domain with your request. possible: only the name is the same or similar."},"match":{"type":"object","properties":{"on":{"type":"string","enum":["identifier","email","phone","linkedin","domain","name"],"description":"What matched: an identifier such as a CRD, a channel, a company domain, or a name."},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The value that matched, such as the email address or the identifier with its scheme. Null when the match is on a name."}},"required":["on","value"],"additionalProperties":false,"description":"Why this record was matched."},"companies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"relationship":{"type":"string","description":"What the contact is at this company, such as employee or owner."},"is_primary":{"type":"boolean","description":"True for the company the contact works at."}},"required":["id","name","relationship","is_primary"],"additionalProperties":false},"description":"The companies the existing contact is connected to, to help tell people apart."}},"required":["object","id","name","title","confidence","match","companies"],"additionalProperties":false,"description":"An existing contact that may be the same person."},"description":"Existing contacts that may be the same person. Exact matches come first."},"companies":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"company"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The existing company's id. To connect a contact to it, send it as company.id."},"name":{"type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}]},"confidence":{"type":"string","enum":["exact","possible"],"description":"exact: the record shares an identifier, email, phone, LinkedIn profile or company domain with your request. possible: only the name is the same or similar."},"match":{"type":"object","properties":{"on":{"type":"string","enum":["identifier","email","phone","linkedin","domain","name"],"description":"What matched: an identifier such as a CRD, a channel, a company domain, or a name."},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The value that matched, such as the email address or the identifier with its scheme. Null when the match is on a name."}},"required":["on","value"],"additionalProperties":false,"description":"Why this record was matched."}},"required":["object","id","name","domain","confidence","match"],"additionalProperties":false,"description":"An existing company that may be the same company."},"description":"Existing companies that may be the same company. Only present when the request would create a company."}},"required":["contacts","companies"],"additionalProperties":false}},"required":["type","code","message","param","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"description":"Every error response has this shape."}}},"paths":{"/v1/contacts/{id}":{"get":{"operationId":"contacts.retrieve","summary":"Retrieve a contact","description":"Returns a contact with every company they are currently connected to and every active channel.","tags":["Contacts"],"parameters":[{"name":"id","in":"path","required":true,"description":"The contact's id.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The contact's id."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"contact"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The contact's job title."},"address":{"type":"object","properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}]},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false},"owner_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The team member this contact is assigned to."},"relationship":{"type":"object","properties":{"status":{"type":"string","enum":["active","churned"],"description":"churned when your organization's relationship with this person has ended."},"first_engaged_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When your organization first reached this person. Null if never."},"churned_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When the relationship ended. Null unless churned."},"churn_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Why the relationship ended. Null unless churned."}},"required":["status","first_engaged_at","churned_at","churn_reason"],"additionalProperties":false,"description":"Your organization's relationship with this person."},"company":{"anyOf":[{"type":"object","properties":{"object":{"type":"string","const":"company"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}]},"relationship":{"type":"string","enum":["employee","advisor","executive","owner","board_member","registered_rep","affiliate","recruiter","consultant"],"description":"What the contact is at this company."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The contact's job title at this company."}},"required":["object","id","name","domain","relationship","title"],"additionalProperties":false,"description":"A company the contact is connected to."},{"type":"null"}],"description":"The company the contact works at. Null when none is recorded, including when the contact has companies but none is marked primary."},"companies":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"company"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}]},"relationship":{"type":"string","enum":["employee","advisor","executive","owner","board_member","registered_rep","affiliate","recruiter","consultant"],"description":"What the contact is at this company."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The contact's job title at this company."},"is_primary":{"type":"boolean","description":"True for the company the contact works at. A contact has at most one."}},"required":["object","id","name","domain","relationship","title","is_primary"],"additionalProperties":false,"description":"A company the contact is currently connected to."},"description":"Every company the contact is currently connected to, with the primary first."},"channels":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"channel"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["email","phone","linkedin"],"description":"The kind of channel: email, phone or linkedin."},"value":{"type":"string","description":"The value to show. Phone numbers are in international format, such as +16172531000. Emails and LinkedIn URLs are shown as entered."},"normalized":{"type":"string","description":"The form used to compare channels. Phones are in international format, emails are lowercase, and LinkedIn URLs are reduced to the host and path. Two channels of the same type are the same channel when this matches."},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A free text label, such as Work or Mobile."},"is_primary":{"type":"boolean","description":"The contact's main channel of this type. A contact has at most one per type."},"active":{"type":"boolean","description":"False when the channel has been deactivated. Deactivated channels are kept but not used."},"source":{"type":"string","enum":["manual","api","enrichment","inbound"],"description":"Where the channel came from. manual: added by your team. api: added through the API. enrichment: found by rvmpd research. inbound: the contact wrote to you from it."},"editable":{"type":"boolean","description":"False for channels found by rvmpd research. Those can be made primary, deactivated or activated, but their value and label cannot be changed and they cannot be deleted."},"verified":{"type":"boolean","description":"True when the value has passed a verification check."},"verified_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When the last verification check passed."}},"required":["object","id","type","value","normalized","label","is_primary","active","source","editable","verified","verified_at"],"additionalProperties":false,"description":"A way to reach a contact."},"description":"The contact's active channels, with each type's primary first."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["object","id","name","title","address","owner_id","relationship","company","companies","channels","created_at","updated_at"],"additionalProperties":false,"description":"A person your organization keeps a record for."}}}},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
