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

# Read a merchant's onboarding

> Where a merchant stands on its way to live, and what's needed next. Follow it by polling: only going live, a suspension and a reinstatement send an event. A merchant the credential can't reach answers 404.

Credentials: `partner`, `merchant`

Permission: `onboarding:get`



## OpenAPI

````yaml /api-reference/v1/openapi.json get /merchants/{id}/onboarding
openapi: 3.1.0
info:
  title: Quidkey API
  version: 1.0.0
  description: >-
    The Quidkey public API.


    Within a version, a response can carry what this document doesn't list yet:
    a new field, a new value of an enum, a new error code. Handle a value you
    don't recognise rather than refusing the response. A client generated from
    this document turns an `enum` into a closed type unless told otherwise, so
    turn on its option for unknown values, such as openapi-generator's
    `enumUnknownDefaultCase`. A request is held to what's listed: a value it
    doesn't list is refused.
  contact:
    name: Quidkey
    url: https://docs.quidkey.com
servers:
  - url: https://api.quidkey.com/v1
security:
  - bearer: []
tags:
  - name: account_owner
  - name: agreement
  - name: agreement_acceptance
  - name: api_key
  - name: bank
  - name: bank_account
  - name: capability
  - name: country
  - name: identity_verification
  - name: legal_entity
  - name: merchant
  - name: party
  - name: payment_link
  - name: payout
  - name: transaction
  - name: webhook_endpoint
paths:
  /merchants/{id}/onboarding:
    get:
      tags:
        - merchant
      summary: Read a merchant's onboarding
      description: >-
        Where a merchant stands on its way to live, and what's needed next.
        Follow it by polling: only going live, a suspension and a reinstatement
        send an event. A merchant the credential can't reach answers 404.


        Credentials: `partner`, `merchant`


        Permission: `onboarding:get`
      operationId: merchant.getOnboarding
      parameters:
        - name: id
          in: path
          required: true
          schema:
            minLength: 1
            type: string
        - name: view
          in: query
          required: false
          description: The representation to answer with.
          schema:
            type: string
            enum:
              - full
            default: full
      responses:
        '200':
          description: The onboarding, in the full view.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                additionalProperties: false
                type: object
                required:
                  - result
                  - entities
                  - not_included
                properties:
                  result:
                    $ref: '#/components/schemas/OnboardingFull'
                  entities:
                    additionalProperties: false
                    description: Nothing can be included here.
                    type: object
                    properties: {}
                  not_included:
                    type: array
                    items:
                      $ref: '#/components/schemas/NotIncludedEntry'
        '400':
          description: '`VALIDATION_FAILED`: The request is malformed or failed validation.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - VALIDATION_FAILED
        '401':
          description: '`UNAUTHENTICATED`: A valid bearer token is required.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - UNAUTHENTICATED
        '403':
          description: >-
            `FORBIDDEN`: This credential doesn't have permission for this
            endpoint.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - FORBIDDEN
        '404':
          description: '`NOT_FOUND`: Not found.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - NOT_FOUND
        '406':
          description: '`NOT_ACCEPTABLE`: This endpoint doesn''t offer the format in Accept.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - NOT_ACCEPTABLE
        '429':
          description: '`RATE_LIMITED`: Too many requests.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - RATE_LIMITED
        '500':
          description: '`INTERNAL_ERROR`: Something went wrong on our side.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - INTERNAL_ERROR
        '503':
          description: '`SERVICE_UNAVAILABLE`: The service is busy. Try again shortly.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - SERVICE_UNAVAILABLE
components:
  headers:
    RequestId:
      description: Identifies this request. Quote it to support.
      schema:
        type: string
    RetryAfter:
      description: How many seconds to wait before retrying.
      schema:
        minimum: 0
        type: integer
  schemas:
    OnboardingFull:
      additionalProperties: false
      type: object
      required:
        - _type
        - _uri
        - _view
        - id
        - created_at
        - updated_at
        - submitted_at
        - status
        - tasks
        - required_actions
        - merchant
        - capabilities
      properties:
        _type:
          const: onboarding
          type: string
        _uri:
          pattern: ^/
          description: The canonical URI, relative to the version root.
          type: string
        _view:
          const: full
          type: string
        id:
          type: string
        created_at:
          anyOf:
            - format: date-time
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$
              type: string
            - type: 'null'
        updated_at:
          anyOf:
            - format: date-time
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$
              type: string
            - type: 'null'
        submitted_at:
          anyOf:
            - format: date-time
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$
              type: string
            - type: 'null'
        status:
          type: string
          enum:
            - setting_up
            - in_review
            - action_required
            - live
          description: >-
            Where the onboarding stands.


            - `setting_up`: Details are still being filled in, and nothing is
            with Quidkey yet.

            - `in_review`: With Quidkey, and nothing is needed from you.

            - `action_required`: With Quidkey, and a task is waiting on you
            again.

            - `live`: Activated and not suspended, and for a company, enrolled
            for `virtual_accounts` too.
        tasks:
          type: array
          items:
            additionalProperties: false
            type: object
            required:
              - key
              - status
            properties:
              key:
                type: string
                enum:
                  - legal_entity
                  - parties
                  - identity_verifications
                  - bank_accounts
                  - submission
              status:
                type: string
                enum:
                  - blocked
                  - not_started
                  - action_required
                  - ready
                  - completed
          description: '`parties` and `identity_verifications` are absent for an individual.'
        required_actions:
          type: array
          items:
            $ref: '#/components/schemas/RequiredAction'
          description: >-
            What's needed next, apart from each capability's own actions. It
            doesn't ask for a capability to be requested: read `capabilities`
            for where each stands.


            - `LEGAL_ENTITY_REQUIRED`: Actor `api`. Create the merchant's legal
            entity.

            - `LEGAL_ENTITY_INCOMPLETE`: Actor `api`. The legal entity is
            missing the details `fields` names.

            - `LEGAL_ENTITY_MORE_INFORMATION_REQUIRED`: Actor `api`. Quidkey
            needs more information about the legal entity.

            - `LEGAL_ENTITY_REJECTED`: Actor `api`. Quidkey turned the legal
            entity down, which hands it back to the merchant.

            - `PARTY_REQUIRED`: Actor `api`. `target` is the legal entity, which
            needs a party it has no record of yet: a director, or a person
            holding 25% or more.

            - `PARTY_INCOMPLETE`: Actor `api`. The party is missing the details
            `fields` names. There is one action per party, for each party this
            merchant can read: one that's another merchant's legal entity is
            `SHARED_PARTY_PENDING`'s.

            - `PARTY_MORE_INFORMATION_REQUIRED`: Actor `api`. Quidkey needs more
            information about the party in `target`, whatever it has decided of
            the others. It appears while Quidkey has verified no party: it
            verifies at least one itself, and an approved identity check doesn't
            do that.

            - `PARTY_REJECTED`: Actor `api`. Quidkey turned down every party
            this merchant can read, the one in `target` among them. The merchant
            needs at least one party Quidkey verifies, which an approved
            identity check isn't.

            - `SHARED_PARTY_PENDING`: Actor `quidkey`. A party of this merchant
            is also another merchant's legal entity, which can't be read through
            this merchant, and Quidkey has to settle it before the step it holds
            can go on. It has no `target` and no `fields`, and appears once
            whatever the number of such parties.

            - `CORPORATE_SHAREHOLDER_OWNERS_REQUIRED`: Actor `person`. A company
            the business register lists as a shareholder needs saying who, if
            anyone, holds 25% or more through it. Someone signed in to Console
            answers it, and this API can't.

            - `DIRECTOR_IDENTITY_NOT_STARTED`: Actor `api`. No identity check is
            open for a party with the `director` role, so start one. `target` is
            the party someone in Console chose for the check, where someone did,
            and `null` otherwise. Absent while no party this merchant can read
            could be checked for it. A party that's another merchant's legal
            entity isn't readable through this merchant, so no identity-check
            code is published for it.

            - `OWNER_IDENTITY_NOT_STARTED`: Actor `api`. No identity check is
            open for a person holding 25% or more, whatever their role, so start
            one. `target` is the party someone in Console chose for the check,
            where someone did, and `null` otherwise. Absent while no party this
            merchant can read could be checked for it. A party that's another
            merchant's legal entity isn't readable through this merchant, so no
            identity-check code is published for it.

            - `PARTY_IDENTITY_NOT_VERIFIED`: Actor `person`. The identity check
            of the party in `target` is under way, and may be waiting on the
            person: it reads `created`, `in_progress` or `processing`.
            `hosted_link` is `null`. A party has one check under way at a time,
            so calling `:verifyIdentity` on it answers with the one running
            rather than start another. Where the legal entity is under more than
            one merchant, that check can be another merchant's, which this
            merchant can't read.

            - `PARTY_IDENTITY_IN_REVIEW`: Actor `quidkey`. The identity check of
            the party in `target` reads `in_review`, parked for Quidkey's
            review, and nothing is needed from you. Starting another check
            replaces it, and spends a paid check.

            - `PARTY_IDENTITY_CHECK_FAILED`: Actor `api`. The identity check of
            the party in `target` ended without passing: it was declined or
            abandoned, couldn't be completed, or its link expired. Start
            another, which spends a paid check.

            - `PARTY_INVITATION_WAITING`: Actor `person`. The person invited in
            `target` hasn't given their details yet. `target` is an invitation,
            with no `_link`.

            - `PARTY_INVITATION_EXPIRED`: Actor `person`. The invitation in
            `target` lapsed before it was answered, and the person is still
            needed: invite them again in Console. `target` is an invitation,
            with no `_link`.

            - `BANK_ACCOUNT_REQUIRED`: Actor `api`. Add an active `owned`
            account with the role `payout`.

            - `AGREEMENT_ACCEPTANCE_REQUIRED`: Actor `api`. The merchant hasn't
            accepted the agreement in `target`, its current version. Record the
            person's acceptance through `agreement_acceptance`. Quidkey won't
            sign the merchant off until every one is accepted. A merchant
            Quidkey has signed off isn't asked.

            - `BANK_DEBIT_AUTHORIZATION_REQUIRED`: Actor `api`. The merchant
            hasn't authorised debits from the active `owned` account in
            `target`. Record the person's `bank_debit_authorization` through
            `agreement_acceptance`, naming the account. Quidkey won't sign the
            merchant off until every account has one. A merchant Quidkey has
            signed off isn't asked.

            - `ONBOARDING_SUBMISSION_REQUIRED`: Actor `person`. Someone at the
            merchant signs in and submits on the page in `hosted_link`, which
            carries no merchant and opens on the signed-in user's current
            merchant. `hosted_link` is `null` where there's no such page to
            give.

            - `QUIDKEY_REVIEW_PENDING`: Actor `quidkey`. The onboarding is with
            Quidkey, which verifies the legal entity and at least one party
            itself, then signs the merchant off. An approved identity check
            doesn't verify a party.

            - `ACCOUNTS_BEING_SET_UP`: Actor `quidkey`. Quidkey is setting up
            the merchant's accounts.

            - `QUIDKEY_ACTIVATION_PENDING`: Actor `quidkey`. Quidkey has signed
            the merchant off, and has yet to put it live or to reinstate it, or,
            for a company, `virtual_accounts` has yet to be enrolled: read it
            for what it waits on.
        merchant:
          $ref: '#/components/schemas/MerchantLink'
        capabilities:
          $ref: '#/components/schemas/CapabilityCollectionLink'
    NotIncludedEntry:
      additionalProperties: false
      type: object
      required:
        - link
        - reason
      properties:
        link:
          $ref: '#/components/schemas/AnyLink'
        reason:
          type: string
          enum:
            - no_permission
            - not_published
          description: >-
            Why this link has no entity.


            - `no_permission`: This credential can't read it. Fetching it
            answers 403, or 404 where a 403 would reveal that it exists.

            - `not_published`: The API doesn't show it: a type it doesn't
            publish, or a record it doesn't show on a type it does, such as a
            failed payout. Fetching it, where it has a URI, answers 404.
    Error:
      additionalProperties: false
      type: object
      required:
        - error
      properties:
        error:
          additionalProperties: false
          type: object
          required:
            - code
            - message
            - details
            - retryable
            - request_id
          properties:
            code:
              description: Branch on this. New codes can appear.
              type: string
            message:
              description: For people. It can change.
              type: string
            details:
              type: array
              items:
                $ref: '#/components/schemas/ErrorDetail'
            retryable:
              description: >-
                Whether sending the same request again unchanged, after a wait,
                can succeed with nothing else changing.
              type: boolean
            request_id:
              description: Quote this to support.
              type: string
    RequiredAction:
      description: Something that has to happen before a resource can move on.
      additionalProperties: false
      type: object
      required:
        - code
        - message
        - actor
        - target
        - fields
        - hosted_link
      properties:
        code:
          description: >-
            Public and stable, and listed on the field that holds it. New codes
            can appear, so handle any you don't recognise.
          type: string
        message:
          type: string
        actor:
          type: string
          enum:
            - api
            - person
            - quidkey
          description: >-
            Who resolves it. `api`: your integration makes the API call the code
            names. `person`: someone acts, in Console or on the page in
            `hosted_link`. `quidkey`: there's nothing for you to do, because
            Quidkey retries it or its staff handle it.
        target:
          anyOf:
            - $ref: '#/components/schemas/AnyLink'
            - type: 'null'
        fields:
          type: array
          items:
            type: string
          description: >-
            The public fields of `target` it's about, with dotted paths into an
            address, such as `registered_address.city`. `[]` unless the code
            names fields.
        hosted_link:
          anyOf:
            - $ref: '#/components/schemas/HostedLink'
            - type: 'null'
    MerchantLink:
      additionalProperties: false
      type: object
      required:
        - _link
        - _type
        - id
      properties:
        _link:
          pattern: ^/
          type: string
        _type:
          const: merchant
          type: string
        id:
          type: string
      x-link-target:
        resource: merchant
        kind: resource
        is_published: true
        views:
          - full
    CapabilityCollectionLink:
      additionalProperties: false
      type: object
      required:
        - _link
        - _type
      properties:
        _link:
          pattern: ^/
          type: string
        _type:
          const: collection
          type: string
      x-link-target:
        resource: capability
        kind: collection
        is_published: true
        views:
          - full
    AnyLink:
      anyOf:
        - additionalProperties: false
          type: object
          required:
            - _link
            - _type
            - id
          properties:
            _link:
              pattern: ^/
              type: string
            _type:
              type: string
            id:
              type: string
        - additionalProperties: false
          type: object
          required:
            - _type
            - id
          properties:
            _type:
              type: string
            id:
              type: string
      x-link-target:
        resource: any
        kind: any
        is_published: true
    ErrorDetail:
      anyOf:
        - additionalProperties: false
          type: object
          required:
            - field
            - message
          properties:
            field:
              type: string
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - required_actions
            - message
          properties:
            required_actions:
              description: The `required_actions` codes holding this back.
              type: array
              items:
                type: string
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - available_percent
            - message
          properties:
            available_percent:
              $ref: '#/components/schemas/Percent'
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - agreement
            - message
          properties:
            agreement:
              $ref: '#/components/schemas/AgreementLink'
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - agreement
            - current_agreement
            - message
          properties:
            agreement:
              $ref: '#/components/schemas/AgreementLink'
            current_agreement:
              $ref: '#/components/schemas/AgreementLink'
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - legal_entity
            - message
          properties:
            legal_entity:
              $ref: '#/components/schemas/LegalEntityLink'
            message:
              type: string
    HostedLink:
      description: >-
        A page a person opens, on HTTPS in production. Its URL can carry a
        token, so treat it as a secret.
      additionalProperties: false
      type: object
      required:
        - url
        - expires_at
      properties:
        url:
          format: uri
          type: string
        expires_at:
          anyOf:
            - format: date-time
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$
              type: string
            - type: 'null'
    Percent:
      pattern: ^\d+(\.\d+)?$
      description: 'A percentage as a decimal string: `"25.00"` is 25%.'
      type: string
    AgreementLink:
      additionalProperties: false
      type: object
      required:
        - _link
        - _type
        - id
      properties:
        _link:
          pattern: ^/
          type: string
        _type:
          const: agreement
          type: string
        id:
          type: string
      x-link-target:
        resource: agreement
        kind: resource
        is_published: true
        views:
          - full
    LegalEntityLink:
      additionalProperties: false
      type: object
      required:
        - _link
        - _type
        - id
      properties:
        _link:
          pattern: ^/
          type: string
        _type:
          const: legal_entity
          type: string
        id:
          type: string
      x-link-target:
        resource: legal_entity
        kind: resource
        is_published: true
        views:
          - full
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.