Corporation Profile

Before You Start

Read the following guides before proceeding:

Overview

GET /api/v1/corporations is the single read for everything the corporation is and can do: legal
details captured at registration and enriched by KYB, the profile and verification statuses, the
evaluated capability list, and the actions available right now.

The response is computed per request. Capabilities are evaluated against the corporation's country,
verification levels, bank accounts and cards at the moment of the call — it is not a cached snapshot.

Read the Corporation

GET /api/v1/corporations

Requires a corporation token. No permission is declared — any authenticated employee can read it.

Response:

{
  "corporation_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
  "owner_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
  "corporation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "corporation_name": "Acme Inc",
  "corporation_type": "LimitedLiability",
  "registration_number": "12345678",
  "status": "Active",
  "status_reason": "KYB verification passed",
  "verification_status": "Approved",
  "verification_levels": [
    { "level": "SDD", "status": "Approved" }
  ],
  "passed_levels": ["SDD"],
  "corporation_registration_address": {
    "line1": "10 Downing Street",
    "line2": "Flat 2",
    "city": "London",
    "state": "",
    "country": "GB",
    "postal_code": "SW1A 2AA"
  },
  "corporation_contact_details": {
    "name": "Alex Grey",
    "email": "[email protected]",
    "phone_number": "+447700900123"
  },
  "freshdesk_id": "1234567890",
  "capabilities": [
    {
      "type": "VisaVirtualCard",
      "status": "Active",
      "status_reason": "",
      "prerequisites": [],
      "verification_requirements": [{ "type": "SDD", "order": 1 }]
    },
    {
      "type": "SepaOut3rdParty",
      "status": "NotFulfilled",
      "status_reason": "Prerequisite capability is not active yet",
      "prerequisites": ["SepaAccount"],
      "verification_requirements": [{ "type": "SDD", "order": 1 }]
    }
  ],
  "actions": [
    { "type": "IssueVirtualCard", "relative_path": "/api/v1/cards/virtual" },
    { "type": "ActivateSepaDetails", "relative_path": "/api/v1/bank/accounts" }
  ]
}

short_id is documented on the schema but is not returned — the read path does not carry it today.

The registration call does not populate the address or contact details.
corporation_registration_address and corporation_contact_details come from KYB. They are absent
until the corporation has been through the SDK session, and corporation_registration_address.country
is what capability evaluation reads. A corporation with no legal address on record resolves to an
empty capability list, and every capability check then fails with Capability is not active.

Code

const response = await fetch(`${baseUrl}/api/v1/corporations`, {
  headers: { 'Authorization': `Bearer ${corporationToken}` }
});
const corporation = await response.json();

response = requests.get(
    f"{base_url}/api/v1/corporations",
    headers={"Authorization": f"Bearer {corporation_token}"},
)
corporation = response.json()

req, _ := http.NewRequest("GET", baseURL+"/api/v1/corporations", nil)
req.Header.Set("Authorization", "Bearer "+corporationToken)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var corporation CorporationResponse
json.NewDecoder(resp.Body).Decode(&corporation)

Profile Status

Pending → Active
   ↓         ↓
Blocked ←→ Active
   ↓
Deleted

Profile status is advanced by Wirex, not by the partner. There is no endpoint to change it.

Allowed Actions

actions[] is the corporation's answer to "what can this corporation do right now". Each entry is a
capability decision already made, so the client does not have to re-derive it from the capability list.

The list is unordered — evaluators run over a map. Match on type, never on position.

Verify appears while verification is in progress, not while it is outstanding. A corporation
that has never started KYB has no Verify action; call
POST /api/v1/corporations/level-token directly to start it.

SendSpeiTransfer and ReceiveSpeiDeposit are both gated on SpeiAccount rather than on the
matching SpeiOut1stParty / SpeiIn1stParty capability. Their presence means the SPEI account is
live, not that the directional capability was separately evaluated. Read the capability list before
relying on either.

Update the Support Identifier

PUT /api/v1/corporations/freshdesk-id

Requires a corporation token. No permission is declared.

Request body:

{
  "freshdesk_id": "1234567890"
}

Response:

{}

Error Handling

{
  "error_reason": "ErrorGeneral",
  "error_description": "Failed to query corporation",
  "error_category": {
    "category": "CategoryInternalFailure",
    "http_status_code": 500
  }
}

Server Errors (500)

The bank and card reads are not optional enrichment — GET /api/v1/corporations fails entirely when
either is unavailable, because capability evaluation depends on both. Treat a 500 here as transient
and retry rather than assuming the corporation is broken.