Create a Contact

Create a contact — a person saved into this workspace.

POST https://api.aisa.one/apis/v1/apollo/contacts

cURL

Create contact with deduplication

curl --request POST \
  --url https://api.aisa.one/apis/v1/apollo/contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "[e-mail]",
  "first_name": "Jane",
  "last_name": "Doe",
  "organization_name": "Example Corp",
  "run_dedupe": true,
  "title": "Product Manager"
}
'

200

{
  "contact": {}
}

Create a contact — a person saved into this workspace. Search with post_apollo_contacts_search first to avoid duplicates, which Apollo does not reject here the way it rejects duplicate account domains. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation. To look someone up without saving them, use post_apollo_people_match.

First time? Point any MCP client at https://mcp.aisa.one/mcp — Claude Code, Codex, Cursor, VS Code and the rest. Authorization is OAuth: the client opens a browser, you click Allow once, and there is no key to paste. Your agent then reaches every endpoint through a few meta tools: search, list_categories, get_details and batch_quote are free, batch_use is billed per call. Setup per client is in Connect via MCP; the live tool list and what each call costs are on aisa.one/mcp.

Set this endpoint up in your agent →

Request contract

• Method and path: POST /apis/v1/apollo/contacts
• Availability: enabled
• Request URL template: https://api.aisa.one/apis/v1/apollo/contacts
• Runtime facts: 9ab7612cf2d53be794cbf1d65d4a257f986ac6783e53c7c3a5d868e4593061c3

Complete OpenAPI definition

Effective request and pricing declaration (including authentication and referenced schemas):

{
  "operationId": "post_apollo_contacts",
  "method": "POST",
  "path": "/apis/v1/apollo/contacts",
  "servers": [
    {
      "url": "https://api.aisa.one"
    }
  ],
  "parameters": [],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "examples": {
          "Create contact with deduplication": {
            "summary": "Create a new contact with deduplication enabled",
            "value": {
              "email": "[e-mail]",
              "first_name": "Jane",
              "last_name": "Doe",
              "organization_name": "Example Corp",
              "run_dedupe": true,
              "title": "Product Manager"
            }
          },
          "Create contact without deduplication": {
            "summary": "Create a new contact without deduplication (default behavior)",
            "value": {
              "email": "[e-mail]",
              "first_name": "John",
              "last_name": "Smith",
              "organization_name": "Example Corp",
              "title": "Software Engineer"
            }
          }
        },
        "schema": {
          "properties": {
            "account_id": {
              "description": "The Apollo ID for the account. Example: `63f53afe4ceeca00016bdd2f`",
              "type": "string"
            },
            "contact_stage_id": {
              "description": "The Apollo ID for the contact stage. Example: `6095a710bd01d100a506d4ae`",
              "type": "string"
            },
            "corporate_phone": {
              "description": "The work/office phone number. Example: `[phone]`",
              "type": "string"
            },
            "direct_phone": {
              "description": "The primary phone number. Example: `555-555-0133`",
              "type": "string"
            },
            "email": {
              "description": "The email address of the contact. Example: `[e-mail]`",
              "type": "string"
            },
            "first_name": {
              "description": "The first name of the contact you want to create. Example: `Tim`",
              "type": "string"
            },
            "home_phone": {
              "description": "The home phone number. Example: `555-555-0133`",
              "type": "string"
            },
            "label_names": {
              "description": "Lists to which the contact belongs.",
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "last_name": {
              "description": "The last name of the contact you want to create. Example: `Zheng`",
              "type": "string"
            },
            "mobile_phone": {
              "description": "The mobile phone number. Example: `555-555-0133`",
              "type": "string"
            },
            "organization_name": {
              "description": "The name of the contact's employer (company). Example: `apollo`",
              "type": "string"
            },
            "other_phone": {
              "description": "Alternative phone number. Example: `555-555-0133`",
              "type": "string"
            },
            "present_raw_address": {
              "description": "The personal location for the contact. Example: `Atlanta, United States`",
              "type": "string"
            },
            "run_dedupe": {
              "default": false,
              "description": "Set to `true` to match against your existing contacts instead of always creating a new one. The default value is `false`. <br><br>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. <br><br>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. <br><br>When deduplication is enabled, performance may be slightly impacted due to the additional matching checks. See the endpoint description for full details.",
              "type": "boolean"
            },
            "title": {
              "description": "The current job title that the contact holds. Example: `senior research analyst`",
              "type": "string"
            },
            "typed_custom_fields": {
              "additionalProperties": {
                "type": "string"
              },
              "description": "Add information to <a href=\"https://knowledge.apollo.io/hc/en-us/articles/4412498825869-Create-Custom-Contact-Fields\" target=\"_blank\">custom fields</a> in Apollo. <br><br><b>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.</b> <br><br>To utilize this parameter successfully, call the <a href=\"https://docs.apollo.io/reference/get-a-list-of-all-custom-fields\">get a list of all custom fields</a> 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. <br><br><b>Example</b>: When the <a href=\"https://docs.apollo.io/reference/get-a-list-of-all-custom-fields\">get a list of all custom fields</a> endpoint returns an `id` of field: \n * `\"60c39ed82bd02f01154c470a\"` (datetime) \n \n\n then the value passed should be: \n\n `{\"60c39ed82bd02f01154c470a\": \"2025-08-07\"}`",
              "example": {
                "60c39ed82bd02f01154c470a": "2025-08-07"
              },
              "type": "object"
            },
            "website_url": {
              "description": "The corporate website URL. Example: `https://www.apollo.io/`",
              "type": "string"
            }
          },
          "type": "object"
        }
      }
    },
    "required": true
  },
  "x-aisa-status": "enabled",
  "x-aisa-pricing": {
    "cost_contract": "fixed_success",
    "customer_pricing": "fixed_success",
    "default_request_estimate_usd": 0.012,
    "estimate_source": "profile_seed",
    "evidence_source": "request_snapshot"
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  }
}

Cost and request rules

Published reference price: $0.012 USD per successful request. Account-specific pricing and final settlement may differ.

Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar.

• Default request reference estimate (USD): 0.012
• Cost contract: fixed_success
• Settlement evidence source: request_snapshot

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

account_id · string

The Apollo ID for the account. Example: 63f53afe4ceeca00016bdd2f

contact_stage_id · string

The Apollo ID for the contact stage. Example: 6095a710bd01d100a506d4ae

corporate_phone · string

The work/office phone number. Example: [phone]

direct_phone · string

The primary phone number. Example: 555-555-0133

email · string

The email address of the contact. Example: [e-mail]

first_name · string

The first name of the contact you want to create. Example: Tim

home_phone · string

The home phone number. Example: 555-555-0133

label_names · string[]

Lists to which the contact belongs.

last_name · string

The last name of the contact you want to create. Example: Zheng

mobile_phone · string

The mobile phone number. Example: 555-555-0133

organization_name · string

The name of the contact's employer (company). Example: apollo

other_phone · string

Alternative phone number. Example: 555-555-0133

present_raw_address · string

The personal location for the contact. Example: Atlanta, United States

run_dedupe · boolean · default: false

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.

title · string

The current job title that the contact holds. Example: senior research analyst

typed_custom_fields · object

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:

• "60c39ed82bd02f01154c470a" (datetime)

then the value passed should be:

{"60c39ed82bd02f01154c470a": "2025-08-07"}

Show child attributes

Example:

{ "60c39ed82bd02f01154c470a": "2025-08-07" }

website_url · string

The corporate website URL. Example: https://www.apollo.io/

Response

200

application/json

Successful response

contact · object

Created contact