> ## Documentation Index > Fetch the complete documentation index at: https://docs.slate.inc/llms.txt > Use this file to discover all available pages before exploring further. # Create or update an account (upsert) > Idempotently creates the account if none exists for your `(owner, crid)`, or updates the existing one, from the snapshot in the request body. Re-sending the same `crid` updates the same account. On create, Slate assigns and returns the account's `accountId`. Send the account's *current* full state; this is the primary way a daily inventory feed keeps Slate in sync. ## OpenAPI ````yaml /api-reference/accounts/openapi.yaml post /v1/accounts openapi: 3.0.0 info: title: Accounts API (DRAFT) version: 0.0.1 contact: name: Slate API Support email: api-support@slate.inc url: https://slate.inc description: >- **DRAFT. Shapes, names, and field sets may change before this is finalized** The Accounts API is how an owner keeps Slate's view of its accounts in sync. An **account** is the primary data entity that Slate services against, mapping to the originating account that the debt is associated with. **Two identifiers.** Slate assigns each account a stable UUID, `accountId` — this is the canonical id and the key for every read and targeted update. You also carry your own identifier for the account, `crid` (the account number in your system), which is unique within your organization (`owner`). You do not know Slate's `accountId` until the account has been created, so the first write is an **upsert** keyed on your `crid`; the response returns the assigned `accountId`, which you use from then on (and can re-resolve any time via `GET /v1/accounts?crid=...`). **Upsert.** `POST /v1/accounts` idempotently creates the account if new or updates it if one already exists for your `(owner, crid)`. Send the account's current state as a full snapshot — this is how a daily inventory feed keeps Slate in sync. Targeted updates use a partial `PATCH /v1/accounts/{accountId}` — send only the fields that changed (balance, status, placement, legal, …) — for owners that prefer not to resend the whole account. **Scoping & auth.** Every request is scoped to a single `owner`; `crid` is unique only within an owner. List requests take a required `owner` query parameter (which your token must be authorized to read); writes are scoped to the single `owner` on your bearer token. **Money.** All monetary amounts are **US dollars with two decimal places**, sent and returned as decimal **strings** (e.g. `"1250.75"`) to avoid floating-point rounding. Do not send minor units (cents) or bare JSON numbers. servers: - url: https://api.slate.inc/accounts description: Production - url: https://api.uat.slate.inc/accounts description: UAT (staging) security: - bearerAuth: [] paths: /v1/accounts: post: summary: Create or update an account (upsert) description: >- Idempotently creates the account if none exists for your `(owner, crid)`, or updates the existing one, from the snapshot in the request body. Re-sending the same `crid` updates the same account. On create, Slate assigns and returns the account's `accountId`. Send the account's *current* full state; this is the primary way a daily inventory feed keeps Slate in sync. operationId: upsertAccount requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpsertAccountRequest' responses: '200': description: An existing account was updated. content: application/json: schema: $ref: '#/components/schemas/Account' '201': description: A new account was created. content: application/json: schema: $ref: '#/components/schemas/Account' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/ServerError' components: schemas: UpsertAccountRequest: type: object description: >- A full snapshot of the account's current state. Matched to an existing account on `(owner, crid)`; fields omitted are treated as unset/unchanged-to-empty, so send everything you know each time. required: - crid - creditorId - status - currentBalance properties: crid: type: string description: Your identifier for the account — the upsert key within your owner. creditorId: type: string format: uuid description: >- The creditor this account belongs to (Slate creditor UUID); must be one your owner manages. status: $ref: '#/components/schemas/AccountStatus' currentBalance: type: string format: decimal pattern: ^-?\d+(\.\d{1,2})?$ x-go-type: decimal.Decimal x-go-type-import: path: github.com/shopspring/decimal description: >- The current amount owed, in US dollars, as a decimal string (e.g. "1250.75"). accountNumber: type: string description: The current client/account number. portfolioId: type: string description: Portfolio identifier, if part of a purchased portfolio. chargeOffDate: type: string format: date description: The charge-off date, if applicable. placement: $ref: '#/components/schemas/PlacementRequest' legal: $ref: '#/components/schemas/LegalRecord' metadata: $ref: '#/components/schemas/Metadata' Account: type: object description: The full account aggregate as Slate holds it. required: - accountId - owner - crid - creditorId - status - currentBalance properties: accountId: type: string format: uuid readOnly: true description: >- Slate's stable UUID for the account — the canonical identifier, assigned by Slate on create. owner: type: string description: The organization that owns this account in Slate (your owner code). crid: type: string description: >- Your identifier for the account (the account number in your system) — the natural key the upsert matches on, unique within your owner. matterId: type: string format: uuid readOnly: true description: >- Current active matter UUID for the account. Currently created on initial account creation, but support will be added later for managing an accounts matters, both current and historical. accountNumber: type: string description: >- The current client/account number. May change over the life of the account (e.g. when paper is sold). accountNumberHistory: type: array readOnly: true description: >- The history of account-number changes for this account, oldest first. Empty when the number has never changed. Read-only — recorded automatically whenever `accountNumber` changes. items: $ref: '#/components/schemas/AccountNumberChange' creditorId: type: string format: uuid description: >- The creditor this account belongs to (Slate creditor UUID). Register creditors via `POST /v1/creditors`; must be one your owner manages. portfolioId: type: string nullable: true description: >- Portfolio identifier, when the account is part of a purchased portfolio. Absent for forwarded/placed paper. status: $ref: '#/components/schemas/AccountStatus' closedOn: type: string format: date nullable: true description: The date the account was closed; null while `ACTIVE`. currentBalance: type: string format: decimal pattern: ^-?\d+(\.\d{1,2})?$ x-go-type: decimal.Decimal x-go-type-import: path: github.com/shopspring/decimal description: >- The current amount owed, in US dollars, as a decimal string (e.g. "1250.75"). chargeOffDate: type: string format: date nullable: true description: The date the account was charged off, if applicable. placement: $ref: '#/components/schemas/Placement' legal: $ref: '#/components/schemas/LegalRecord' createdOn: type: string format: date-time readOnly: true description: When Slate first created the account. lastUpdated: type: string format: date-time readOnly: true description: When the account was last updated in Slate. metadata: $ref: '#/components/schemas/Metadata' AccountStatus: type: string description: >- Account lifecycle status. Binary: `ACTIVE` (being serviced) or `CLOSED` (resolved, returned, or otherwise done). enum: - ACTIVE - CLOSED PlacementRequest: type: object required: - firmId properties: firmId: type: string format: uuid description: >- The firm (Slate firm UUID) to place the account with. Register firms via `POST /v1/firms`; must be one your owner manages. date: type: string format: date description: When the account was placed. Defaults to today. feeStructure: type: string description: The fee arrangement for the placement. feeRateType: type: string description: How the fee rate is expressed. balance: type: string format: decimal pattern: ^-?\d+(\.\d{1,2})?$ x-go-type: decimal.Decimal x-go-type-import: path: github.com/shopspring/decimal description: >- The balance at the time of placement, in US dollars, as a decimal string. LegalRecord: type: object nullable: true description: >- The account's legal activity. A suit and/or a judgment; either may be absent. properties: suit: $ref: '#/components/schemas/Suit' judgment: $ref: '#/components/schemas/Judgment' Metadata: type: object description: >- Custom key/value pairs you can attach to an object for reporting, analytics, or attributes Slate does not model natively — inspired by Stripe metadata. Values are strings. Limits: at most 50 keys, each key at most 40 characters and each value at most 500 characters. On a partial update (PATCH) the keys you send are merged into the existing metadata; send a key with an empty-string value to remove it. An account upsert (full snapshot) replaces the whole map. additionalProperties: type: string example: region: west portfolio_tier: gold AccountNumberChange: type: object description: A single recorded change of the account's client/account number. required: - previousAccountNumber - newAccountNumber - changedOn properties: previousAccountNumber: type: string description: The account number prior to the change. newAccountNumber: type: string description: The account number after the change. changedOn: type: string format: date-time description: When the change was recorded. changedBy: type: string description: Who recorded the change (the caller's identity, or a system actor). Placement: type: object nullable: true description: >- The servicing firm the account is currently placed with, and its fee terms. Null when the account is not placed. properties: firmId: type: string format: uuid description: The firm (Slate firm UUID) currently handling the account. date: type: string format: date description: When the account was placed with this firm. feeStructure: type: string description: The fee arrangement for the placement (e.g. contingency). feeRateType: type: string description: How the fee rate is expressed. balance: type: string format: decimal pattern: ^-?\d+(\.\d{1,2})?$ x-go-type: decimal.Decimal x-go-type-import: path: github.com/shopspring/decimal description: >- The balance at the time of placement, in US dollars, as a decimal string. Error: type: object required: - message properties: message: type: string description: A human-readable description of what went wrong. Suit: type: object description: A filed lawsuit on the account. required: - filedDate properties: filedDate: type: string format: date description: The date the suit was filed. Its presence is what records the suit. Judgment: type: object description: A judgment entered on the account. required: - enteredDate properties: enteredDate: type: string format: date description: >- The date judgment was entered. Its presence is what records the judgment. amount: type: string format: decimal pattern: ^-?\d+(\.\d{1,2})?$ x-go-type: decimal.Decimal x-go-type-import: path: github.com/shopspring/decimal description: The total judgment amount, in US dollars, as a decimal string. responses: BadRequest: description: The request was malformed or failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing, invalid, or insufficiently scoped credentials. content: application/json: schema: $ref: '#/components/schemas/Error' ServerError: description: Unexpected internal error. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Owner-scoped bearer token. The `owner` all requests are scoped to is derived from the token. ````