> ## Documentation Index > Fetch the complete documentation index at: https://docs.outboundlegal.com/llms.txt > Use this file to discover all available pages before exploring further. # Add or update clients > Adds or updates up to 500 clients. A client is found by `external_id`, otherwise by name + street address + ZIP (all three). Blank or missing fields never erase what's saved. A client who already has a different `external_id` is reported as a `conflict`, not merged. You get one result per client, in the order you sent them. If saving fails part-way, nothing in the request is saved (500). ## OpenAPI ````yaml /api/openapi.json post /clients openapi: 3.1.0 info: title: OutboundLegal API version: 1.0.0 description: >- Connect Zapier or your own tools to OutboundLegal: add and update your clients, mark a case settled, and send our prospects to your CRM as cold leads. Every request needs an API key from Settings → Integrations → API keys, sent as `Authorization: Bearer obl_…`. Limit: 120 requests per minute per key. servers: - url: https://app.outboundlegal.com/api/v1 description: Production security: - bearerAuth: [] tags: - name: Account description: Which account a key belongs to. - name: Clients description: Your firm's own clients (not crash prospects). - name: Prospects description: Crash prospects in your counties, as cold leads. Digital bundle only. paths: /clients: post: tags: - Clients summary: Add or update clients description: >- Adds or updates up to 500 clients. A client is found by `external_id`, otherwise by name + street address + ZIP (all three). Blank or missing fields never erase what's saved. A client who already has a different `external_id` is reported as a `conflict`, not merged. You get one result per client, in the order you sent them. If saving fails part-way, nothing in the request is saved (500). operationId: upsertClients requestBody: required: true content: application/json: schema: type: object required: - clients properties: clients: type: array maxItems: 500 items: allOf: - $ref: '#/components/schemas/ClientInput' - type: object properties: new_settlement: type: boolean default: false description: >- Only matters when this client's `settled_on` changes. `true`: a new settlement (may get another thank-you letter). `false` (default): a correction (no second letter). example: clients: - external_id: M-1042 first_name: Ana last_name: Diaz address_line1: 12 Elm St city: Newark state: NJ zip: '07102' case_type: Motor vehicle accident responses: '200': description: >- One result per client, in order. A client that failed checks has `status: "error"` and a `message`; the others are still saved. content: application/json: schema: type: object required: - results properties: results: type: array items: $ref: '#/components/schemas/UpsertResult' example: results: - index: 0 status: created id: 0b6c1d8e-6a43-4c1e-9d0f-2f5b9a7e4c21 '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/Internal' components: schemas: ClientInput: type: object description: >- A client to add or update. Every field is optional, but a new client needs a first or last name. Unknown fields are ignored. Blank values never erase what's saved. properties: first_name: type: string maxLength: 200 last_name: type: string maxLength: 200 address_line1: type: string maxLength: 300 description: Street address. address_line2: type: string maxLength: 300 description: Apartment, suite, unit. city: type: string maxLength: 200 state: type: string description: 2-letter US state (a full state name is also accepted). examples: - NJ zip: type: - string - integer description: >- 5- or 9-digit ZIP. A ZIP that lost its leading zero (7102) is fixed to 07102. examples: - '07102' email: type: string format: email maxLength: 320 phone: type: - string - integer description: 10 to 15 digits; any formatting is fine. case_type: type: string maxLength: 200 description: >- Free text, e.g. "Motor vehicle accident". Client letters can be limited to certain case types. opened_on: type: string description: 'Date the case opened: `2026-10-13`, `10/13/2026` or `Oct 13, 2026`.' settled_on: type: string description: Date the case settled, same formats as `opened_on`. external_id: type: - string - integer maxLength: 200 description: The client's id in your case system. Send it whenever you have it. do_not_mail: type: - boolean - string description: >- `true` stops all client letters to this person. Also accepts yes/no. The API can turn this on, never off. UpsertResult: type: object required: - index - status properties: index: type: integer description: >- Position of this client in your request (0 for `POST /cases/settled`). status: type: string enum: - created - updated - conflict - error id: type: string format: uuid description: The client's id, when saved. message: type: string description: What went wrong, for `conflict` and `error`. Error: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' ErrorBody: type: object required: - code - message properties: code: type: string enum: - unauthorized - forbidden - not_enabled - bundle_required - rate_limited - invalid_request - not_found - conflict - cursor_stale - internal description: Branch on this. It doesn't change. message: type: string description: A sentence a person can read. It may change. responses: InvalidRequest: description: >- `invalid_request`: a parameter or the body isn't right. The message says what to fix. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_request message: limit must be a whole number from 1 to 100. Unauthorized: description: >- `unauthorized`: no key, a badly formed key, or a key that isn't valid or was revoked. headers: WWW-Authenticate: description: >- Sent when the key is missing or badly formed: `Bearer realm="OutboundLegal"`. schema: type: string content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: 'Send your API key as: Authorization: Bearer obl_…' Forbidden: description: >- `forbidden`: the account's access is suspended, or the key belongs to a view-only login. `not_enabled`: the API isn't turned on for this account yet. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_enabled message: The API isn't turned on for this account yet. RateLimited: description: >- `rate_limited`: more than 120 requests in a minute with this key. Wait the number of seconds in `Retry-After`, then try again. headers: Retry-After: description: Seconds to wait before trying again. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limited message: Too many requests. The limit is 120 per minute per key. Internal: description: '`internal`: something went wrong on our side. Try again shortly.' content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key from Settings → Integrations → API keys. Keys look like `obl_` followed by 43 letters, numbers, `-` or `_`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.