# Save Companies

`POST https://api.getprospect.com/v2/companies/save`

Save companies into your workspace, optionally into company lists. Send company ids, or identify a company by linkedin_id, linkedin_url or domain (at most 50 such items per request). The answer buckets every item into saved, not_matched, invalid and failed, echoing its identifier. A company already saved keeps its first saved_at, so a retry is safe. A ledger failure answers 200 with the items under failed (failed_count > 0). Free: spends no credits; 1 unit of the enrich rate limit per item without an id, none for a save by id.

## Authentication

Pass your API key in the `x-api-key` header.

## Body parameters

- `data` (one of[], required): Companies to save (1-500): a company id, or an object identifying it by id, linkedin_id, linkedin_url or domain. At most 50 items may come without an id.
- `list_ids` (string[], optional): Company lists to put every saved company in (0-20), each a company list of your workspace (another id answers 400). Default: none.

## Example request

```bash
curl --request POST \
  --url https://api.getprospect.com/v2/companies/save \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "data": [
    "696fb12757da999990585cfd"
  ],
  "list_ids": [
    "66f2c1d0a1b2c3d4e5f60718"
  ]
}
'
```

## Response 200

Every item in exactly one bucket, with the bucket counts in `metadata` (`credits` is null: nothing is spent). Retry the items under `failed`.

```json
{
  "success": true,
  "data": {
    "saved": [
      {
        "identifier": "crm-17",
        "id": "696fb12757da999990585cfd",
        "matched_by": "domain",
        "list_ids": [],
        "all_list_ids": [
          "66f2c1d0a1b2c3d4e5f60718"
        ],
        "saved_at": "2026-09-14T08:03:51.000Z"
      }
    ],
    "not_matched": [
      {
        "identifier": "crm-18",
        "attempted": [
          "linkedin_url"
        ]
      }
    ],
    "invalid": [
      {
        "identifier": "crm-19",
        "reason": "name is not a save identifier: resolve the company with companies_enrich first and save its id.",
        "skipped": [
          "name"
        ]
      }
    ],
    "failed": []
  },
  "metadata": {
    "timestamp": "2026-10-02T12:27:10.726Z",
    "total": 3,
    "saved_count": 1,
    "not_matched_count": 1,
    "invalid_count": 1,
    "failed_count": 0,
    "credits": null
  }
}
```

## Response 400

Invalid request (`VALIDATION_ERROR`): a malformed body or unknown key, more than 50 items without an id (`out_of_range`), one identifier with different lookup keys (`conflicting_fields`), or a `list_ids` entry that is not a company list of your workspace.

```json
{
  "success": false,
  "data": null,
  "metadata": {
    "timestamp": "2026-10-02T12:27:10.726Z"
  },
  "errors": [
    {
      "name": "VALIDATION_ERROR",
      "message": "lists is not a field of this request",
      "payload": {
        "field": "lists",
        "code": "unknown_field",
        "received_value": [
          "x"
        ],
        "received_type": "object",
        "allowed_fields": [
          "data",
          "list_ids",
          "search_id"
        ]
      }
    }
  ]
}
```

## Response 401

Missing, unknown or inactive credentials (`UNAUTHORIZED`).

## Response 429

Over the `enrich` rate limit (`RATE_LIMIT`); wait `Retry-After` seconds. Sent only where rate limits are enforced.

## Response 500

Unexpected server error.