# Get onboarding status

Returns the current status of one client onboarding case. When the case is `APPROVED`, use the returned `clientId` in Client Account API client paths.

Product: Client Account API
API reference version: 0.3.0 (current)
OpenAPI contract: https://docs.sandbox.axiym.io/openapi/client-account-api/0.3.0.yaml
Canonical page: https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/onboarding/getOnboardingStatus

[Compact reference](/client-account-api/api-reference/0.3.0/onboarding/getOnboardingStatus.md)

## GET /onboardings/{clientId}

## Servers

```json
[
  {
    "url": "https://partner-api.sandbox.axiym.io/api/v1",
    "description": "Sandbox"
  },
  {
    "url": "https://partner-api.axiym.io/api/v1",
    "description": "Production"
  }
]
```

## Authentication

```json
{
  "security": [
    {
      "Default": []
    }
  ],
  "securitySchemes": {
    "Default": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    }
  }
}
```

## Parameters

### path: clientId

```json
{
  "name": "clientId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "1d2f7f5e-8a3b-4c6d-9e0f-2a4b6c8d0e2f"
    ]
  },
  "description": "Client identifier (UUID) assigned when an onboarding case is created. It identifies the onboarding case and, once active, the client's Client Account API resources. The client must belong to your partnership; anyone else's id returns 404."
}
```

### header: X-Request-Id

```json
{
  "name": "X-Request-Id",
  "in": "header",
  "required": false,
  "description": "Optional identifier for tracing a request end to end. A UUID is recommended. Axiym returns it in the `X-Request-Id` response header and records it in logs. If omitted, Axiym generates one. Include it when contacting support.\n",
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  }
}
```

## Responses

### 200

```json
{
  "description": "Current onboarding case.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OnboardingCase"
      }
    }
  }
}
```

### 401

```json
{
  "description": "Authentication is missing or invalid.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 401,
            "message": "Unauthorized",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 403

```json
{
  "description": "Your access token does not permit this operation or access to the requested resource.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 403,
            "message": "Forbidden",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 404

```json
{
  "description": "The requested resource was not found.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message: either the generic 'Not Found' or a domain-specific one such as 'Client Not Found'."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 404,
            "message": "Not Found",
            "errors": null
          }
        },
        "Client not found": {
          "summary": "Client not found",
          "value": {
            "code": 404,
            "message": "Client Not Found",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 500

```json
{
  "description": "An unexpected server error prevented the request from completing.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 500,
            "message": "Internal Error",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

## Operation metadata

```json
{
  "tags": [
    "Onboarding"
  ],
  "operationId": "getOnboardingStatus"
}
```

## Referenced definitions

- [`#/components/parameters/ClientId`](#definition-1)
- [`#/components/parameters/RequestId`](#definition-2)
- [`#/components/schemas/OnboardingCase`](#definition-3)
- [`#/components/schemas/Address`](#definition-4)
- [`#/components/schemas/Currency`](#definition-5)
- [`#/components/schemas/DisbursementAccount`](#definition-6)
- [`#/components/responses/Unauthorized`](#definition-7)
- [`#/components/responses/Forbidden`](#definition-8)
- [`#/components/responses/NotFound`](#definition-9)
- [`#/components/responses/InternalError`](#definition-10)

### definition-1

`#/components/parameters/ClientId`

```json
{
  "name": "clientId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "1d2f7f5e-8a3b-4c6d-9e0f-2a4b6c8d0e2f"
    ]
  },
  "description": "Client identifier (UUID) assigned when an onboarding case is created. It identifies the onboarding case and, once active, the client's Client Account API resources. The client must belong to your partnership; anyone else's id returns 404."
}
```

### definition-2

`#/components/parameters/RequestId`

```json
{
  "name": "X-Request-Id",
  "in": "header",
  "required": false,
  "description": "Optional identifier for tracing a request end to end. A UUID is recommended. Axiym returns it in the `X-Request-Id` response header and records it in logs. If omitted, Axiym generates one. Include it when contacting support.\n",
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  }
}
```

### definition-3

`#/components/schemas/OnboardingCase`

```json
{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "format": "uuid",
      "description": "Client identifier (UUID).",
      "examples": [
        "b7e8c1a2-9f43-4d2e-8a6b-1c2d3e4f5a6b"
      ]
    },
    "code": {
      "type": "string",
      "description": "Human-readable client code.",
      "examples": [
        "AXI000221"
      ]
    },
    "legalEntityName": {
      "type": "string",
      "description": "Official name of the company.",
      "examples": [
        "Acme Corporation"
      ]
    },
    "legalAddress": {
      "description": "Legal address.",
      "$ref": "#/components/schemas/Address"
    },
    "incorporationDate": {
      "type": "string",
      "description": "Date the legal entity was established.",
      "format": "date",
      "examples": [
        "2020-01-15"
      ]
    },
    "registrationDate": {
      "type": "string",
      "description": "Date the company joined your network.",
      "format": "date",
      "examples": [
        "2020-02-01"
      ]
    },
    "status": {
      "type": "string",
      "description": "Onboarding application status.",
      "enum": [
        "ONBOARDING",
        "APPROVED",
        "REJECTED"
      ],
      "examples": [
        "ONBOARDING"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Currency code (ISO 4217 fiat or supported stablecoin).",
      "examples": [
        "USD"
      ]
    },
    "disbursementAccount": {
      "$ref": "#/components/schemas/DisbursementAccount",
      "description": "Payment Network bank account that receives funding disbursements for this client (the funding destination)."
    },
    "partnerClientId": {
      "type": "string",
      "description": "Your reference for this client.",
      "examples": [
        "my-internal-ref-001"
      ]
    },
    "paymentRails": {
      "type": "string",
      "description": "Payment rail — a configured settlement channel Axiym uses to hold and move funds: a banking partner for fiat (e.g. `ZENUS_BANK`, `FREEMARKET`) or a blockchain network for crypto (e.g. `TRON`, `AVALANCHE`). Codes are returned by `GET /settings/payment-rails`.",
      "examples": [
        "ZENUS_BANK"
      ]
    }
  },
  "required": [
    "clientId",
    "code",
    "legalEntityName",
    "status"
  ],
  "description": "Snapshot of a client onboarding application. Created in the submitted state and reviewed by Axiym compliance; while the review is in progress the status stays ONBOARDING. An approved application ends in APPROVED; a rejected application ends in REJECTED."
}
```

### definition-4

`#/components/schemas/Address`

```json
{
  "description": "Registered legal address of a business.",
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "City or locality.",
      "examples": [
        "New York"
      ]
    },
    "country": {
      "type": "string",
      "pattern": "^[A-Z]{2}$",
      "description": "ISO 3166-1 alpha-2 country code.",
      "examples": [
        "US"
      ]
    },
    "address": {
      "type": "string",
      "description": "First address line.",
      "examples": [
        "350 Fifth Avenue"
      ]
    },
    "addressExtended": {
      "type": "string",
      "description": "Second address line, where applicable.",
      "examples": [
        "Suite 1200"
      ]
    },
    "district": {
      "type": "string",
      "description": "State / County / Province / Region portion of the address. If the country is US or Canada, then district is required and should use the two-letter code for the subdivision.",
      "examples": [
        "NY"
      ]
    },
    "postalCode": {
      "type": "string",
      "description": "Postal or ZIP code.",
      "examples": [
        "10115"
      ]
    }
  },
  "required": [
    "postalCode",
    "country",
    "address"
  ]
}
```

### definition-5

`#/components/schemas/Currency`

```json
{
  "type": "string",
  "description": "Currency code — ISO 4217 (e.g. USD, EUR) or a supported digital currency (USDT, USDC).",
  "examples": [
    "USD"
  ]
}
```

### definition-6

`#/components/schemas/DisbursementAccount`

```json
{
  "type": "object",
  "properties": {
    "accountNumber": {
      "type": "string",
      "description": "Bank account number.",
      "examples": [
        "0123456789"
      ]
    }
  },
  "description": "Bank account at the Payment Network that receives funding disbursements."
}
```

### definition-7

`#/components/responses/Unauthorized`

```json
{
  "description": "Authentication is missing or invalid.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 401,
            "message": "Unauthorized",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-8

`#/components/responses/Forbidden`

```json
{
  "description": "Your access token does not permit this operation or access to the requested resource.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 403,
            "message": "Forbidden",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-9

`#/components/responses/NotFound`

```json
{
  "description": "The requested resource was not found.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message: either the generic 'Not Found' or a domain-specific one such as 'Client Not Found'."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 404,
            "message": "Not Found",
            "errors": null
          }
        },
        "Client not found": {
          "summary": "Client not found",
          "value": {
            "code": 404,
            "message": "Client Not Found",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-10

`#/components/responses/InternalError`

```json
{
  "description": "An unexpected server error prevented the request from completing.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 500,
            "message": "Internal Error",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```