> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recotap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Accounts

> Push new accounts into Recotap

`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.

```bash theme={null}
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](../segments/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`**

```json theme={null}
{
  "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 |

<Info>
  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.
</Info>