Create Accounts

POST /accounts Pushes accounts into Recotap. Max 100 per request. Deduplication is by domain. By default (upsert omitted or false), if an account with the same domain already exists, the item is returned as failed. Set upsert: true to update existing accounts instead. Returns HTTP 200 regardless of per-item outcome. Check each item’s status in the results array.

curl -X POST "https://eapi.recotap.com/api/v1/accounts" \
  -H "X-Api-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": [
      {
        "externalId": "crm-001",
        "domain": "acme.com",
        "name": "Acme Corp",
        "shortName": "Acme",
        "linkedinUrl": "https://www.linkedin.com/company/acme-corp",
        "tags": ["enterprise", "q2-target"],
        "customFields": { "CONTRACT_VALUE_C": 75000 }
      }
    ],
    "segmentId": "663xyz...",
    "upsert": true
  }'

Request body

Field	Type	Required	Description
`accounts`	array	Yes	Min 1, max 100 account objects
`segmentId`	string	No	Recotap segment ID — must be static type and active or draft status. All successfully created or updated accounts are added to this segment. Use List Segments to retrieve available segment IDs.
`upsert`	boolean	No	Default `false`. When `true`, accounts with a matching domain are updated with the provided fields. When `false` or omitted, existing accounts are returned as `failed` instead.

Account object

Field	Type	Required	Description
`domain`	string	Yes	Primary domain. Cleaned before storage: `https://`, `www.`, and trailing paths are stripped and the value is lowercased. `https://www.acme.com/foo` is stored as `acme.com`. Used as the deduplication key — cannot be changed via upsert.
`name`	string	Yes	Company name e.g. `"Acme Corp"`
`externalId`	string	No	Your own reference ID for this account, stored in Recotap for your use. Not used for deduplication.
`shortName`	string	No	Abbreviated company name e.g. `"Acme"`
`linkedinUrl`	string	No	LinkedIn company page URL e.g. `"https://www.linkedin.com/company/acme-corp"`
`tags`	string[]	No	Free-form tag strings e.g. `["enterprise", "q2-target"]`
`customFields`	object	No	Key-value pairs using Recotap custom field keys e.g. `{ "CONTRACT_VALUE_C": 75000 }`. Keys must exist as active custom fields. Unknown keys cause the item to fail. On upsert, only the keys present in the payload are updated — omitted keys are left unchanged.

Response data

{
  "results": [
    { "rtp_aid": "663abc...", "domain": "acme.com", "status": "created" },
    { "rtp_aid": "663def...", "domain": "existing.com", "status": "updated" },
    { "rtp_aid": "663ghi...", "domain": "duplicate.com", "status": "failed", "error": "Account with domain 'duplicate.com' already exists. Set upsert: true to update this account via this endpoint." },
    { "rtp_aid": null, "domain": "bad-fields.com", "status": "failed", "error": "Custom field key(s) not found: INVALID_KEY_C. Unable to add this account." }
  ],
  "summary": { "total": 4, "created": 1, "updated": 1, "failed": 2 }
}

Per-item status values

Status	Cause
`created`	Account successfully added
`updated`	Account with a matching domain was found and updated (`upsert: true`)
`failed`	e.g. an account with this domain already exists and `upsert` is `false` or omitted, or `customFields` contains an unknown key

If segmentId is provided, it is validated before any accounts are processed. The segment must exist, be of type static, and have a status of active or draft. If validation fails, the entire request is rejected with 400 and no accounts are processed. When upsert: true, accounts that already belong to the segment are silently skipped — no duplicate membership is created.

Getting Started

API Reference

Resources