> ## Documentation Index > Fetch the complete documentation index at: https://docs.instantcompliance.ai/llms.txt > Use this file to discover all available pages before exploring further. # Replace designated services > Replace the complete set of designated services provided to an entity. Pass stable codes returned by `GET /designated-services`. An empty `service_codes` array removes every current assignment. Adding a designated service applies the same CDD, risk, classification, and audit behaviour as the in-app editor — for entities that includes upgrading `kyb_status` from `NOT_REQUIRED` to `NOT_STARTED` — but it does **not** start a verification, send a verification request, consume credits, or charge the organisation or customer. Requires the `customers:write` scope. Include an `Idempotency-Key` header to make retries safe for 24 hours. Replace the entity's designated-service set with `service_codes` — the same operation as the in-app editor: the designated flag is derived, the entity's risk rating is recomputed, classification stays in sync, and the change is audited. A designated service being added can upgrade `kyb_status` from `NOT_REQUIRED` to `NOT_STARTED` (due diligence becomes owed). **No KYB is started and no credits are charged** — your back-office team chooses the KYB method and starts verification in-app. An empty `service_codes` array is an explicit "no designated services". The path `{id}` accepts our UUID or your `external_id`. ## OpenAPI ````yaml PUT /entities/{id}/designated-services openapi: 3.1.0 info: title: Instant Compliance API version: 1.0.0 summary: External integration API for Instant Compliance. description: | The Instant Compliance v1 API lets your systems push customers into Instant Compliance and pull their verification / AML status back out. Designed for server-to-server use (CRMs, Zapier, internal back-office tools). **Base URL:** `https://app.instantcompliance.ai/api/v1` **Authentication:** Bearer API key — `Authorization: Bearer ic_live_…` Issue keys from **Settings → Developers** in your Instant Compliance organisation. **Scope:** individual customers (`INDIVIDUAL` and `SOLE_TRADER`, KYC) live on `/customers`; entity customers (companies, trusts, partnerships, SMSFs — KYB) live on `/entities`. contact: name: Instant Compliance Support email: support@instantcompliance.ai url: https://instantcompliance.ai license: name: Proprietary servers: - url: https://app.instantcompliance.ai/api/v1 description: Production security: - bearerAuth: [] tags: - name: Customers description: | Create, read, and update individual customer records ingested through the external API. - name: Entities description: | Create, read, and update entity customer records (companies, trusts, partnerships, SMSFs). Entities verify via KYB instead of KYC; the API ingests the record and reports status — verification is started by your back-office team in-app. - name: Designated services description: | Read-only catalog of the designated-service codes accepted when creating customers. - name: Groups description: | Create group workspaces (multi-party deals/matters — e.g. one per property for real-estate integrators) and discover the group templates available to your organisation. Requires the Groups feature to be enabled for your organisation. paths: /entities/{id}/designated-services: parameters: - in: path name: id required: true schema: type: string description: | Entity identifier. Accepts either Instant Compliance's UUID (`550e8400-…`) or your own `external_id`. put: tags: - Entities summary: Replace an entity's designated services description: | Replace the complete set of designated services provided to an entity. Pass stable codes returned by `GET /designated-services`. An empty `service_codes` array removes every current assignment. Adding a designated service applies the same CDD, risk, classification, and audit behaviour as the in-app editor — for entities that includes upgrading `kyb_status` from `NOT_REQUIRED` to `NOT_STARTED` — but it does **not** start a verification, send a verification request, consume credits, or charge the organisation or customer. Requires the `customers:write` scope. Include an `Idempotency-Key` header to make retries safe for 24 hours. operationId: replaceEntityDesignatedServices parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReplaceCustomerDesignatedServicesRequest' example: service_codes: - PRO-FORMATION responses: '200': description: | Updated entity record. `designated_services` is the complete normalized set now assigned to the entity. content: application/json: schema: $ref: '#/components/schemas/EntityWithDesignatedServices' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/ForbiddenScope' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' components: parameters: IdempotencyKey: in: header name: Idempotency-Key required: false schema: type: string maxLength: 255 description: | Caller-supplied unique key for safe retries. Repeat the same key within 24 hours and we replay the original response instead of repeating the side effect. Reusing the key with a *different* request body returns **409 idempotency_conflict**. schemas: ReplaceCustomerDesignatedServicesRequest: type: object required: - service_codes additionalProperties: false properties: service_codes: $ref: '#/components/schemas/DesignatedServices' EntityWithDesignatedServices: allOf: - $ref: '#/components/schemas/Entity' - type: object required: - designated_services properties: designated_services: $ref: '#/components/schemas/DesignatedServices' DesignatedServices: type: array maxItems: 64 items: type: string maxLength: 64 description: > The specific designated service(s) provided to the customer, as stable catalog codes. An empty array is an explicit "no designated services". Unknown or non-designated codes are rejected with `422 validation_failed`. The catalog is also available programmatically via `GET /designated-services`. **Professional services** | Code | Service | |------|---------| | `PRO-FORMATION` | Company or trust formation | | `PRO-PURCHASE-SALE` | Company or trust purchase/sale | | `PRO-RESTRUCTURE` | Business restructuring services | | `PRO-REAL-ESTATE` | Real estate professional services (conveyancing / legal) | | `PRO-CLIENT-MONEY` | Client money/assets management (incl. securities & virtual assets) | | `PRO-FINANCING` | Business financing arrangement services | | `PRO-SHELF` | Shelf company sales | | `PRO-NOMINEE` | Nominee director or shareholder services | | `PRO-REGISTERED-OFFICE` | Registered office address services | **Real estate** | Code | Service | |------|---------| | `RE-BROKER` | Real estate agency (brokering sales) | | `RE-DEVELOPER` | Property development sales | **Financial services** | Code | Service | |------|---------| | `FIN-BANKING` | Banking and deposit services | | `FIN-REMITTANCE` | Money transfer and remittance services | | `FIN-CRYPTO` | Cryptocurrency exchange services | | `FIN-FX` | Foreign currency exchange | | `FIN-LOANS` | Loans and financing services | | `FIN-INVESTMENT` | Investment and securities services | | `FIN-ADVISORY` | Financial advisory services (arranging designated services) | | `FIN-INSURANCE` | Insurance services (life insurance, sinking funds) | | `FIN-SUPER` | Superannuation fund management | | `FIN-PENSION` | Pension, annuity, or retirement account services | | `FIN-STORED-VALUE` | High-value stored value cards | | `FIN-CUSTODIAL` | Custodial and depository services | | `FIN-PAYROLL` | Payroll services for other businesses | **Other designated services** | Code | Service | |------|---------| | `OTH-BULLION` | Bullion trading (precious metals) | | `OTH-GAMBLING` | Gambling services | | `OTH-HIGH-VALUE-GOODS` | High-value goods dealing | example: - PRO-FORMATION - PRO-CLIENT-MONEY Entity: type: object required: - id - type - name - origin - kyb_status - aml - added_via - created_at - updated_at properties: id: type: string format: uuid description: Instant Compliance customer UUID (entities are customers too). external_id: type: string nullable: true type: $ref: '#/components/schemas/EntityType' name: type: string description: The entity's legal name. origin: $ref: '#/components/schemas/EntityOrigin' abn: type: string nullable: true acn: type: string nullable: true country_of_formation: type: string nullable: true description: | ISO 3166-1 alpha-3. `AUS` for Australian entities; the country of formation for international entities. registration_number: type: string nullable: true description: Registry number recorded for international entities. kyb_status: $ref: '#/components/schemas/KycStatus' kyb_started_at: type: string format: date-time nullable: true kyb_completed_at: type: string format: date-time nullable: true contact: $ref: '#/components/schemas/EntityContact' aml: $ref: '#/components/schemas/AmlBlock' added_via: $ref: '#/components/schemas/AddedVia' created_at: type: string format: date-time updated_at: type: string format: date-time example: id: 7c9e6679-7425-40de-944b-e07fc1f90ae7 external_id: crm-ent-311 type: COMPANY name: Acme Holdings Pty Ltd origin: AUSTRALIAN abn: '12345678901' acn: '123456789' country_of_formation: AUS registration_number: null kyb_status: IN_PROGRESS kyb_started_at: '2026-06-23T01:00:00Z' kyb_completed_at: null contact: id: 550e8400-e29b-41d4-a716-446655440000 external_id: crm-7741 full_name: Jane Doe email: jane@example.com kyc_status: PENDING kyc_required: true aml: status: CLEAR screened_at: '2026-06-23T01:12:00Z' last_reviewed_at: null flags: pep: false sanctions: false adverse_media: false terrorism: false added_via: INTEGRATION created_at: '2026-06-22T22:14:00Z' updated_at: '2026-06-23T01:12:05Z' Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - unauthorized - forbidden_scope - not_found - validation_failed - conflict - insufficient_credits - rate_limited - idempotency_conflict - feature_disabled - internal message: type: string details: type: object additionalProperties: true EntityType: type: string enum: - COMPANY - TRUST - PARTNERSHIP - SMSF - OTHER description: | Entity customer types accepted by `/entities`. `SMSF` is treated as a type of trust and `OTHER` as a company for verification purposes, but the type you post round-trips back unchanged. Immutable after creation. EntityOrigin: type: string enum: - AUSTRALIAN - INTERNATIONAL description: | Where the entity is formed. `AUSTRALIAN` (the default) uses ABN/ACN identifiers; `INTERNATIONAL` uses `countryOfFormation` + `registrationNumber`. Immutable after creation. KycStatus: type: string enum: - NOT_STARTED - PENDING - IN_PROGRESS - VERIFIED - FAILED - NOT_REQUIRED - AWAITING_RESUBMISSION EntityContact: type: object nullable: true required: - id - full_name - kyc_status - kyc_required description: The entity's current contact person, or `null` when none is set. properties: id: type: string format: uuid external_id: type: string nullable: true full_name: type: string email: type: string format: email nullable: true kyc_status: $ref: '#/components/schemas/KycStatus' kyc_required: type: boolean description: >- Whether the contact's own KYC is intended to run with the entity's KYB. AmlBlock: type: object required: - status - flags properties: status: $ref: '#/components/schemas/AmlStatus' screened_at: type: string format: date-time nullable: true last_reviewed_at: type: string format: date-time nullable: true flags: type: object required: - pep - sanctions - adverse_media - terrorism properties: pep: type: boolean sanctions: type: boolean adverse_media: type: boolean terrorism: type: boolean AddedVia: type: string description: How the record entered Instant Compliance. enum: - ADMIN_MANUAL - AI_EXTRACTED - CONTACT_PORTAL - BULK_IMPORT - INTEGRATION - SYSTEM AmlStatus: type: string enum: - NOT_SCREENED - IN_PROGRESS - CLEAR - NEEDS_REVIEW - RESOLVED responses: Unauthorized: description: Missing, invalid, expired, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: Invalid or revoked API key. ForbiddenScope: description: API key lacks the required scope. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: forbidden_scope message: This API key does not have the required scope. customers:write details: required_scope: customers:write NotFound: description: No customer matching the supplied id in this organisation. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_found message: Customer not found. ValidationFailed: description: Request payload failed schema validation. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: validation_failed message: Invalid customer payload. details: issues: email: - Must be a valid email address. RateLimited: description: Burst or daily rate limit exceeded for this API key. headers: Retry-After: schema: type: integer description: Seconds to wait before retrying. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limited message: Rate limit exceeded. Slow down and retry shortly. details: limit: 60 window_seconds: 60 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: | Bearer API key issued from **Settings → Developers** in your Instant Compliance organisation. Format: `ic_live_…`. ````