--- updatedAt: 2026-08-21T18:37:58.000Z agentTools: projectIndex: https://docs.apollo.io/llms.txt --- # Create a Contact
Endpoint essentials
API key access api/v1/contacts/create or Master API key
OAuth scopes contact_write
Credit usage 0 credits
Learn more about API pricing and credits.
Contacts are people saved in Apollo.

Use the create a contact endpoint to add a new contact to your team's Apollo account.

By default, Apollo doesn't apply deduplication processes when you create a new contact via API. If your entry has the same name, email address, or other details as an existing contact, Apollo creates a new contact instead of updating the existing contact. To enable deduplication and prevent duplicate contacts, set the run\_dedupe parameter to true.

To update an existing contact, use the update a contact endpoint instead. ### What `run_dedupe` actually does Setting `run_dedupe` to `true` does more than suppress a duplicate. On a match, Apollo **updates that existing contact in place** with your request's values and returns it. The response looks like a creation, but the `id` belongs to the pre-existing contact — so treating every `200` as "a new contact was created" doesn't hold once `run_dedupe` is on. **How Apollo picks the match.** It checks these in order and stops at the first hit, so a match isn't necessarily on email: 1. `id`, if you send one. 2. CRM identifiers: `salesforce_lead_id`, `salesforce_contact_id`, `hubspot_vid`, or a previously merged CRM ID. 3. `person_id`. 4. `email` — compared against the contact's primary email **and** any additional emails stored on it. 5. `first_name` plus `last_name` (or a full name) with a matching company, where the company matches on email domain, `organization_id`, or `organization_name`. Because of step 5, a contact can be matched and updated even when the email you send differs from the stored one. **What the update writes.** It's a field-level overwrite of the values you send, not a merge that prefers existing data: * Fields you **send** overwrite the stored values, with no warning and no record of the previous value. * Fields you **omit** are left untouched, so you don't need to resend the whole record. * An **empty value clears the field** rather than being ignored. * The contact's `email` can itself be overwritten when the match came from a CRM ID, `person_id`, or name-plus-company. `email_status` isn't re-verified, so it can keep reading `verified` while describing the previous address. * Protected once set: `person_id`, `salesforce_lead_id`, and `salesforce_contact_id`. LinkedIn-sourced photos won't replace an existing `photo_url`. **Recommended handling.** To add records without changing existing ones, leave `run_dedupe` off (the default) and reconcile duplicates yourself. To upsert, set it to `true` and send the complete set of fields you want the contact to end up with, since omitted fields keep their old values. To edit a known contact, prefer update a contact with its `id` — explicit, with no matching involved. Bulk create contacts differs: matched contacts are returned in `existing_contacts` **without** being modified. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "apollo-rest-api", "summary": "Programmatic access to Apollo's sales intelligence and engagement platform — data enrichment, prospect and company search, and go-to-market workflow management.", "description": "The Apollo API provides programmatic access to [Apollo](https://www.apollo.io/), the all-in-one sales intelligence and engagement platform. Use it to enrich people and company data (individually or in bulk), search Apollo's database of over 240 million contacts and 30 million companies, and manage accounts, contacts, deals, sequences, tasks, calls, and conversations in your go-to-market workflows.\n\n## Base URL\n\nAll API requests are made to `https://api.apollo.io/api/v1`.\n\n## Authentication\n\n- **Apollo users** authenticate with an API key passed in the `x-api-key` request header. See [Create API Keys](https://docs.apollo.io/docs/create-api-key).\n- **Apollo partners** building integrations on behalf of mutual users authenticate with the [OAuth 2.0 authorization flow](https://docs.apollo.io/docs/use-oauth-20-authorization-flow-to-access-apollo-user-information-partners).\n\n## Rate limits & credits\n\nRate limits and credit consumption depend on your [Apollo pricing plan](https://docs.apollo.io/docs/api-pricing). Check your current limits and usage with the [view API usage stats and rate limits](https://docs.apollo.io/reference/view-api-usage-stats) endpoint. For more details, see [Rate Limits](https://docs.apollo.io/reference/rate-limits) and the [API FAQs](https://docs.apollo.io/docs/apollo-api-faqs).\n\nNew to the API? Start with the [Apollo API overview](https://docs.apollo.io/reference/apollo-api).", "termsOfService": "https://www.apollo.io/terms/api", "contact": { "name": "Apollo API Support", "url": "https://docs.apollo.io/" }, "version": "1.0" }, "servers": [ { "url": "https://api.apollo.io/api/v1" } ], "tags": [ { "name": "Contacts", "description": "Create, update, and search the people your team saves in Apollo." } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "[Recommended] API key, passed in the `x-api-key` request header.\nSee [Create API Keys](https://docs.apollo.io/docs/create-api-key)." }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "OAuth 2.0 access token, used by Apollo partners building integrations.\nSee the [OAuth 2.0 authorization flow](https://docs.apollo.io/docs/use-oauth-20-authorization-flow-to-access-apollo-user-information-partners)." } }, "schemas": { "ErrorDetails": { "type": "object", "description": "Machine-readable detail for an error that uses the new format, returned alongside the endpoint's existing error fields. The legacy error fields at the root level (`error`, `error_code`, `message`, etc) are removed on 2027-02-16, after which `error_details` is the only error payload. Some errors already return `error_details` on its own.", "properties": { "code": { "type": "string", "description": "Stable identifier in the form `DOMAIN.CATEGORY.REASON`. Branch on this value; the human-readable `message` can change.", "example": "AUTH.AUTHENTICATION.CREDENTIALS_MISSING" }, "message": { "type": "string", "description": "Human-readable explanation of what went wrong.", "example": "This request carried no credential Apollo could authenticate." }, "suggestions": { "type": "array", "description": "Ordered, actionable next steps. Each entry carries a `label`, and where relevant the `parameter`, `header`, or `url` it refers to.", "items": { "type": "object", "properties": { "label": { "type": "string", "example": "Send your API key in the X-Api-Key header" }, "url": { "type": "string", "example": "https://docs.apollo.io/reference/authentication" }, "parameter": { "type": "string", "example": "webhook_url" }, "parameters": { "type": "array", "description": "Several parameters, any one of which satisfies the requirement.", "items": { "type": "string" }, "example": [ "name", "domain", "website_url", "linkedin_url" ] }, "header": { "type": "string", "example": "X-Api-Key" }, "example": { "type": "string", "description": "A valid sample value for the parameter named above." }, "retry_after_seconds": { "type": "integer", "description": "On a rate-limit refusal, how long to wait before retrying.", "example": 60 } } } }, "context": { "type": "object", "description": "Values from your request that explain the refusal. Each entry is an object rather than a bare value, so read `context..value`. Absent when the error needs no context.", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "description": { "type": "string" } } }, "example": { "window": { "value": "hourly", "description": "The rate-limit window your request exceeded" } } } } } } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "paths": { "/contacts": { "post": { "summary": "Create a contact", "description": "## Endpoint essentials\n\n**API key access:** `api/v1/contacts/create` or `Master API key`\n\n**OAuth scopes:** `contact_write`\n\n**Credit usage:** `0 credits` — [Learn more about API pricing and credits](https://docs.apollo.io/docs/api-pricing).\n\nContacts are people saved in Apollo.

Use the create a contact endpoint to add a new contact to your team's Apollo account.

By default, Apollo doesn't apply deduplication processes when you create a new contact via API. If your entry has the same name, email address, or other details as an existing contact, Apollo creates a new contact instead of updating the existing contact. To enable deduplication and prevent duplicate contacts, set the run_dedupe parameter to true.

To update an existing contact, use the update a contact endpoint instead.\n\n### What `run_dedupe` actually does\n\nSetting `run_dedupe` to `true` does more than suppress a duplicate. On a match, Apollo **updates that existing contact in place** with your request's values and returns it. The response looks like a creation, but the `id` belongs to the pre-existing contact — so treating every `200` as \"a new contact was created\" doesn't hold once `run_dedupe` is on.\n\n**How Apollo picks the match.** It checks these in order and stops at the first hit, so a match isn't necessarily on email:\n\n1. `id`, if you send one.\n2. CRM identifiers: `salesforce_lead_id`, `salesforce_contact_id`, `hubspot_vid`, or a previously merged CRM ID.\n3. `person_id`.\n4. `email` — compared against the contact's primary email **and** any additional emails stored on it.\n5. `first_name` plus `last_name` (or a full name) with a matching company, where the company matches on email domain, `organization_id`, or `organization_name`.\n\nBecause of step 5, a contact can be matched and updated even when the email you send differs from the stored one.\n\n**What the update writes.** It's a field-level overwrite of the values you send, not a merge that prefers existing data:\n\n* Fields you **send** overwrite the stored values, with no warning and no record of the previous value.\n* Fields you **omit** are left untouched, so you don't need to resend the whole record.\n* An **empty value clears the field** rather than being ignored.\n* The contact's `email` can itself be overwritten when the match came from a CRM ID, `person_id`, or name-plus-company. `email_status` isn't re-verified, so it can keep reading `verified` while describing the previous address.\n* Protected once set: `person_id`, `salesforce_lead_id`, and `salesforce_contact_id`. LinkedIn-sourced photos won't replace an existing `photo_url`.\n\n**Recommended handling.** To add records without changing existing ones, leave `run_dedupe` off (the default) and reconcile duplicates yourself. To upsert, set it to `true` and send the complete set of fields you want the contact to end up with, since omitted fields keep their old values. To edit a known contact, prefer [update a contact](https://docs.apollo.io/reference/update-a-contact) with its `id` — explicit, with no matching involved.\n\n[bulk create contacts](https://docs.apollo.io/reference/bulk-create-contacts) differs: matched contacts are returned in `existing_contacts` **without** being modified.", "tags": [ "Contacts" ], "operationId": "create-a-contact", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "description": "The first name of the contact you want to create. Example: `Tim`" }, "last_name": { "type": "string", "description": "The last name of the contact you want to create. Example: `Zheng`" }, "organization_name": { "type": "string", "description": "The name of the contact's employer (company). Example: `apollo`" }, "title": { "type": "string", "description": "The current job title that the contact holds. Example: `senior research analyst`" }, "account_id": { "type": "string", "description": "The Apollo ID for the account. Example: `63f53afe4ceeca00016bdd2f`" }, "email": { "type": "string", "description": "The email address of the contact. Example: `example@email.com`" }, "website_url": { "type": "string", "description": "The corporate website URL. Example: `https://www.apollo.io/`" }, "label_names": { "type": "array", "description": "Lists to which the contact belongs.", "items": { "type": "string" } }, "contact_stage_id": { "type": "string", "description": "The Apollo ID for the contact stage. Example: `6095a710bd01d100a506d4ae`" }, "present_raw_address": { "type": "string", "description": "The personal location for the contact. Example: `Atlanta, United States`" }, "direct_phone": { "type": "string", "description": "The primary phone number. Example: `555-555-0133`" }, "corporate_phone": { "type": "string", "description": "The work/office phone number. Example: `+44 7700 900852`" }, "mobile_phone": { "type": "string", "description": "The mobile phone number. Example: `555-555-0133`" }, "home_phone": { "type": "string", "description": "The home phone number. Example: `555-555-0133`" }, "other_phone": { "type": "string", "description": "Alternative phone number. Example: `555-555-0133`" }, "typed_custom_fields": { "type": "object", "description": "Add information to custom fields in Apollo.

Your custom fields are unique to your team's Apollo account. This means that the examples in this documentation may not work for your testing purposes.

To utilize this parameter successfully, call the get a list of all custom fields endpoint and identify the `id` value for the custom field, as well as the appropriate data type. For example, if a custom field accepts picklist entries, you need to pass the accompanying `id` value for the picklist entry that you want to use as the input value.

Example: When the get a list of all custom fields endpoint returns an `id` of field: \n * `\"60c39ed82bd02f01154c470a\"` (datetime) \n \n\n then the value passed should be: \n\n `{\"60c39ed82bd02f01154c470a\": \"2025-08-07\"}`", "additionalProperties": { "type": "string" }, "example": { "60c39ed82bd02f01154c470a": "2025-08-07" } }, "run_dedupe": { "type": "boolean", "description": "Set to `true` to match against your existing contacts instead of always creating a new one. The default value is `false`.

When a match is found, Apollo **updates that existing contact in place** with the values you sent and returns it — the `id` in the response belongs to the pre-existing contact, not a new record. Fields you send overwrite the stored values, fields you omit are left untouched, and sending an empty value clears the field.

Matching is checked in order: `id`, CRM identifiers, `person_id`, `email` (against the contact's primary and additional emails), then name plus company. Because of the last rule, a contact can be matched and updated even when the email differs.

When deduplication is enabled, performance may be slightly impacted due to the additional matching checks. See the endpoint description for full details.", "default": false } } }, "examples": { "Create contact without deduplication": { "summary": "Create a new contact without deduplication (default behavior)", "value": { "first_name": "John", "last_name": "Smith", "email": "john.smith@example.com", "organization_name": "Example Corp", "title": "Software Engineer" } }, "Create contact with deduplication": { "summary": "Create a new contact with deduplication enabled", "value": { "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com", "organization_name": "Example Corp", "title": "Product Manager", "run_dedupe": true } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "contact": { "contact_roles": [], "id": "66e34b81740c50074e3d1bd4", "first_name": "Fyodor", "last_name": "Dostoevsky", "name": "Fyodor Dostoevsky", "linkedin_url": null, "title": "Chief Fiction Writer", "contact_stage_id": "6095a710bd01d100a506d4ae", "owner_id": "60affe7d6e270a00f5db6fe4", "creator_id": "60affe7d6e270a00f5db6fe4", "person_id": null, "email_needs_tickling": null, "organization_name": "Apollo.io", "source": "api", "original_source": "api", "organization_id": "5e66b6381e05b4008c8331b8", "headline": null, "photo_url": null, "present_raw_address": "St. Petersburg, Russia", "linkedin_uid": null, "extrapolated_email_confidence": null, "salesforce_id": null, "salesforce_lead_id": null, "salesforce_contact_id": null, "salesforce_account_id": null, "crm_owner_id": null, "created_at": "2024-09-12T20:13:53.207Z", "emailer_campaign_ids": [], "direct_dial_status": null, "direct_dial_enrichment_failed_at": null, "email_status": "verified", "email_source": null, "account_id": "63f53afe4ceeca00016bdd2f", "last_activity_date": null, "hubspot_vid": null, "hubspot_company_id": null, "crm_id": null, "sanitized_phone": "+15555550149", "merged_crm_ids": null, "updated_at": "2024-09-12T20:13:53.331Z", "queued_for_crm_push": true, "suggested_from_rule_engine_config_id": null, "email_unsubscribed": null, "label_ids": [ "66e34b81740c50074e3d1bd0", "66e34b81740c50074e3d1bd1", "66e34b81740c50074e3d1bd2", "66e34b81740c50074e3d1bd3" ], "has_pending_email_arcgate_request": false, "has_email_arcgate_request": false, "existence_level": "full", "email": "fyodo@apollo.io", "email_from_customer": true, "custom_field_errors": {}, "crm_record_url": null, "email_status_unavailable_reason": null, "email_true_status": "User Managed", "updated_email_true_status": true, "contact_rule_config_statuses": [], "source_display_name": "Created from API", "twitter_url": null, "contact_campaign_statuses": [], "contact_emails": [], "next_contact_id": null, "time_zone": "Asia/Krasnoyarsk", "city": "Saint Petersburg", "state": "Saint Petersburg", "country": "Russia", "show_intent": false, "phone_numbers": [ { "raw_number": "555-555-0149", "sanitized_number": "+15555550149", "type": "work_direct", "position": 0, "status": "no_status", "dnc_status": null, "dnc_other_info": null, "dialer_flags": null } ], "account_phone_note": null, "free_domain": false, "is_likely_to_engage": false, "email_domain_catchall": false, "typed_custom_fields": { "5b75f1c11dc2727d43ae3bb9": "test", "5c4296857f799409361890ea": "test2" } }, "labels": [ { "id": "66e34b81740c50074e3d1bd2", "modality": "contacts", "cached_count": 0, "name": "typewriter", "created_at": "2024-09-12T20:13:53.119Z", "updated_at": "2024-09-12T20:13:53.279Z", "user_id": "60affe7d6e270a00f5db6fe4" }, { "id": "66e34b81740c50074e3d1bd1", "modality": "contacts", "cached_count": 0, "name": "fiction", "created_at": "2024-09-12T20:13:53.107Z", "updated_at": "2024-09-12T20:13:53.258Z", "user_id": "60affe7d6e270a00f5db6fe4" }, { "id": "66e34b81740c50074e3d1bd0", "modality": "contacts", "cached_count": 0, "name": "writer", "created_at": "2024-09-12T20:13:53.093Z", "updated_at": "2024-09-12T20:13:53.308Z", "user_id": "60affe7d6e270a00f5db6fe4" }, { "id": "66e34b81740c50074e3d1bd3", "modality": "contacts", "cached_count": 0, "name": "microsoft word", "created_at": "2024-09-12T20:13:53.132Z", "updated_at": "2024-09-12T20:13:53.313Z", "user_id": "60affe7d6e270a00f5db6fe4" } ] } }, "Deduplication-Result": { "summary": "Contact creation with deduplication enabled - existing contact found", "value": { "contact": { "contact_roles": [], "id": "66e34b81740c50074e3d1bd4", "first_name": "Jane", "last_name": "Doe", "name": "Jane Doe", "linkedin_url": null, "title": "Product Manager", "contact_stage_id": "6095a710bd01d100a506d4ae", "owner_id": "60affe7d6e270a00f5db6fe4", "creator_id": "60affe7d6e270a00f5db6fe4", "person_id": null, "email_needs_tickling": null, "organization_name": "Example Corp", "source": "api", "original_source": "api", "organization_id": "5e66b6381e05b4008c8331b8", "headline": null, "photo_url": null, "present_raw_address": null, "linkedin_uid": null, "extrapolated_email_confidence": null, "salesforce_id": null, "salesforce_lead_id": null, "salesforce_contact_id": null, "salesforce_account_id": null, "crm_owner_id": null, "created_at": "2024-09-12T20:13:53.207Z", "emailer_campaign_ids": [], "direct_dial_status": null, "direct_dial_enrichment_failed_at": null, "email_status": "verified", "email_source": null, "account_id": "63f53afe4ceeca00016bdd2f", "last_activity_date": null, "hubspot_vid": null, "hubspot_company_id": null, "crm_id": null, "sanitized_phone": null, "merged_crm_ids": null, "updated_at": "2024-09-12T20:13:53.331Z", "queued_for_crm_push": false, "suggested_from_rule_engine_config_id": null, "email_unsubscribed": null, "label_ids": [], "has_pending_email_arcgate_request": false, "has_email_arcgate_request": false, "existence_level": "full", "email": "jane.doe@example.com", "email_from_customer": true, "custom_field_errors": {}, "crm_record_url": null, "email_status_unavailable_reason": null, "email_true_status": "User Managed", "updated_email_true_status": true, "contact_rule_config_statuses": [], "source_display_name": "Created from API", "twitter_url": null, "contact_campaign_statuses": [], "contact_emails": [], "next_contact_id": null, "time_zone": null, "city": null, "state": null, "country": null, "show_intent": false, "phone_numbers": [], "account_phone_note": null, "free_domain": false, "is_likely_to_engage": false, "email_domain_catchall": false, "typed_custom_fields": {} }, "labels": [], "dedupe_result": { "found_existing": true, "match_reason": "email_match", "existing_contact_id": "66e34b81740c50074e3d1bd4" } } } }, "schema": { "type": "object", "properties": { "contact": { "type": "object", "properties": { "contact_roles": { "type": "array" }, "id": { "type": "string", "example": "66e34b81740c50074e3d1bd4" }, "first_name": { "type": "string", "example": "Fyodor" }, "last_name": { "type": "string", "example": "Dostoevsky" }, "name": { "type": "string", "example": "Fyodor Dostoevsky" }, "linkedin_url": {}, "title": { "type": "string", "example": "Chief Fiction Writer" }, "contact_stage_id": { "type": "string", "example": "6095a710bd01d100a506d4ae" }, "owner_id": { "type": "string", "example": "60affe7d6e270a00f5db6fe4" }, "creator_id": { "type": "string", "example": "60affe7d6e270a00f5db6fe4" }, "person_id": {}, "email_needs_tickling": {}, "organization_name": { "type": "string", "example": "Apollo.io" }, "source": { "type": "string", "example": "api" }, "original_source": { "type": "string", "example": "api" }, "organization_id": { "type": "string", "example": "5e66b6381e05b4008c8331b8" }, "headline": {}, "photo_url": {}, "present_raw_address": { "type": "string", "example": "St. Petersburg, Russia" }, "linkedin_uid": {}, "extrapolated_email_confidence": { "type": "number", "nullable": true }, "salesforce_id": {}, "salesforce_lead_id": {}, "salesforce_contact_id": {}, "salesforce_account_id": {}, "crm_owner_id": {}, "created_at": { "type": "string", "example": "2024-09-12T20:13:53.207Z" }, "emailer_campaign_ids": { "type": "array" }, "direct_dial_status": {}, "direct_dial_enrichment_failed_at": {}, "email_status": { "type": "string", "example": "verified" }, "email_source": {}, "account_id": { "type": "string", "example": "63f53afe4ceeca00016bdd2f" }, "last_activity_date": {}, "hubspot_vid": {}, "hubspot_company_id": {}, "crm_id": {}, "sanitized_phone": { "type": "string", "example": "+15555550149" }, "merged_crm_ids": {}, "updated_at": { "type": "string", "example": "2024-09-12T20:13:53.331Z" }, "queued_for_crm_push": { "type": "boolean", "example": true, "default": true }, "suggested_from_rule_engine_config_id": {}, "email_unsubscribed": {}, "label_ids": { "type": "array", "items": { "type": "string", "example": "66e34b81740c50074e3d1bd0" } }, "has_pending_email_arcgate_request": { "type": "boolean", "example": false, "default": true }, "has_email_arcgate_request": { "type": "boolean", "example": false, "default": true }, "existence_level": { "type": "string", "example": "full" }, "email": { "type": "string", "example": "fyodo@apollo.io" }, "email_from_customer": { "type": "boolean", "example": true, "default": true }, "typed_custom_fields": { "type": "object", "properties": {} }, "custom_field_errors": { "type": "object", "properties": {} }, "crm_record_url": {}, "email_status_unavailable_reason": {}, "email_true_status": { "type": "string", "example": "User Managed" }, "updated_email_true_status": { "type": "boolean", "example": true, "default": true }, "contact_rule_config_statuses": { "type": "array" }, "source_display_name": { "type": "string", "example": "Created from API" }, "twitter_url": {}, "contact_campaign_statuses": { "type": "array", "description": "Array of campaign statuses for the contact, showing their participation in various email sequences", "items": { "type": "object", "description": "Contact campaign status object representing the contact's current state in a specific email sequence", "properties": { "id": { "type": "string", "description": "Unique identifier for this contact campaign status record", "example": "68782af181c7f0002159df25" }, "emailer_campaign_id": { "type": "string", "description": "ID of the email sequence (emailer campaign) this status belongs to", "example": "66e9e215ece19801b219997f" }, "send_email_from_user_id": { "type": "string", "description": "ID of the user who is sending emails for this contact in the sequence", "example": "66302798d03b9601c7934ebf" }, "inactive_reason": { "type": "string", "nullable": true, "description": "Reason why the contact is inactive in this sequence, if applicable", "example": "Sequence inactive" }, "status": { "type": "string", "description": "Current status of the contact in this email sequence", "enum": [ "active", "failed", "paused", "finished" ], "example": "paused" }, "added_at": { "type": "string", "format": "date-time", "description": "Timestamp when the contact was added to this sequence", "example": "2025-07-16T22:42:57.372+00:00" }, "added_by_user_id": { "type": "string", "description": "ID of the user who added this contact to the sequence", "example": "60affe7d6e270a00f5db6fe4" }, "finished_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the contact finished/completed the sequence", "example": null }, "paused_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the contact was paused in the sequence", "example": null }, "auto_unpause_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Scheduled timestamp for automatically unpausing the contact", "example": null }, "send_email_from_email_address": { "type": "string", "nullable": true, "description": "Specific email address used to send emails to this contact", "example": "test.marcus.hale@apollomail.io" }, "send_email_from_email_account_id": { "type": "string", "description": "ID of the email account used to send emails to this contact", "example": "6633baaece5fbd01c791d7ca" }, "manually_set_unpause": { "type": "boolean", "nullable": true, "description": "Whether the unpause was manually set by a user", "example": null }, "failure_reason": { "type": "string", "nullable": true, "description": "Specific reason for failure if status is 'failed'", "enum": [ "hard_bounced", "spam_blocked", "bounced", "past_date_failure" ], "example": null }, "current_step_id": { "type": "string", "nullable": true, "description": "ID of the current step in the sequence that the contact is on", "example": null }, "in_response_to_emailer_message_id": { "type": "string", "nullable": true, "description": "ID of the emailer message this campaign status is in response to", "example": null }, "cc_emails": { "type": "array", "nullable": true, "description": "Email addresses to CC when sending emails to this contact", "items": { "type": "string" }, "example": null }, "bcc_emails": { "type": "array", "nullable": true, "description": "Email addresses to BCC when sending emails to this contact", "items": { "type": "string" }, "example": null }, "to_emails": { "type": "array", "nullable": true, "description": "Additional email addresses to include in TO field when sending emails", "items": { "type": "string" }, "example": null }, "current_step_position": { "type": "integer", "nullable": true, "description": "Position number of the current step in the sequence (1-based indexing)", "example": null } }, "required": [ "id", "emailer_campaign_id", "send_email_from_user_id", "status", "added_at", "added_by_user_id", "send_email_from_email_account_id" ] } }, "contact_emails": { "type": "array" }, "next_contact_id": {}, "time_zone": { "type": "string", "example": "Asia/Krasnoyarsk" }, "city": { "type": "string", "example": "Saint Petersburg" }, "state": { "type": "string", "example": "Saint Petersburg" }, "country": { "type": "string", "example": "Russia" }, "show_intent": { "type": "boolean", "example": false, "default": true }, "phone_numbers": { "type": "array", "items": { "type": "object", "properties": { "raw_number": { "type": "string", "example": "555-555-0149" }, "sanitized_number": { "type": "string", "example": "+15555550149" }, "type": { "type": "string", "example": "work_direct" }, "position": { "type": "integer", "example": 0, "default": 0 }, "status": { "type": "string", "example": "no_status" }, "dnc_status": {}, "dnc_other_info": {}, "dialer_flags": {} } } }, "account_phone_note": {}, "free_domain": { "type": "boolean", "example": false, "default": true }, "is_likely_to_engage": { "type": "boolean", "example": false, "default": true }, "email_domain_catchall": { "type": "boolean", "example": false, "default": true } } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "66e34b81740c50074e3d1bd2" }, "modality": { "type": "string", "example": "contacts" }, "cached_count": { "type": "integer", "example": 0, "default": 0 }, "name": { "type": "string", "example": "typewriter" }, "created_at": { "type": "string", "example": "2024-09-12T20:13:53.119Z" }, "updated_at": { "type": "string", "example": "2024-09-12T20:13:53.279Z" }, "user_id": { "type": "string", "example": "60affe7d6e270a00f5db6fe4" } } } } } } } } }, "401": { "description": "401", "content": { "text/plain": { "examples": { "Check API key": { "value": "Invalid API key. See https://docs.apollo.io/reference/authentication for how to authenticate." } } } } }, "422": { "description": "422", "content": { "application/json": { "examples": { "Check the account ID": { "value": "{\n \"error\": \"Parameters misconfigured. 63f53afe4ceeca00016bdd2fsfsdf is not a valid ID\"\n}" }, "Check the contact stage ID": { "value": "{\n \"error\": \"Parameters misconfigured. 2342432 is not a valid ID\"\n}" } }, "schema": { "oneOf": [ { "title": "Check the account ID", "type": "object", "properties": { "error": { "type": "string", "example": "Parameters misconfigured. 63f53afe4ceeca00016bdd2fsfsdf is not a valid ID" } } }, { "title": "Check the contact stage ID", "type": "object", "properties": { "error": { "type": "string", "example": "Parameters misconfigured. 2342432 is not a valid ID" } } } ] } } } }, "429": { "description": "429", "content": { "application/json": { "examples": { "Too many requests": { "value": "{\n \"message\": \"The maximum number of api calls allowed for api/v1/contacts is 600 times per hour. Please upgrade your plan from https://app.apollo.io/#/settings/plans/upgrade.\",\n \"error_details\": {\n \"code\": \"USAGE.RATE_LIMIT.API_RATE_LIMIT_EXCEEDED\",\n \"message\": \"You have made more API requests than your plan allows in this time window.\",\n \"suggestions\": [\n {\n \"label\": \"Wait until the rate limit resets, then retry the API request.\"\n },\n {\n \"label\": \"Check the Apollo Docs to understand API rate limits and how to use response headers to prevent rate-limit errors.\",\n \"url\": \"https://docs.apollo.io/reference/rate-limits\"\n }\n ],\n \"context\": {\n \"window\": {\n \"value\": \"hour\",\n \"description\": \"The rate limit window that was exhausted, such as \\\"minute\\\" or \\\"hour\\\"\"\n }\n }\n }\n}" } }, "schema": { "type": "object", "properties": { "error_details": { "$ref": "#/components/schemas/ErrorDetails" }, "message": { "deprecated": true, "description": "Legacy error field. Removed on 2027-02-16, after which `error_details` is the only error payload.", "type": "string", "example": "The maximum number of api calls allowed for api/v1/contacts is 600 times per hour. Please upgrade your plan from https://app.apollo.io/#/settings/plans/upgrade." } } } } } } }, "deprecated": false } } }, "x-readme": { "headers": [ { "key": "Cache-Control", "value": "no-cache" }, { "key": "Content-Type", "value": "application/json" } ], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ```