Companies

Overview

A company is the top-level tenant in Custodia. Every user, card, budget, and activity belongs to a company. Create the company first, then use the returned id as companyId in other APIs (for example Create user, Spend templates, or Chart of accounts).

Typical onboarding flow:

1. Create a company: POST /md/api/Companies
2. Create admin users: POST /md/api/User
3. Configure program settings: spend templates, budgets, card products, and so on

Create Company

Creates a new company tenant. Save the returned id: it is the companyId used across the rest of the partner APIs.

Request Body: mandatory fields

Recommended fields for onboarding

Only name is required by the API, but card programs and user provisioning typically need the fields below at create time or shortly after.

Address fields

Used in billingAddress and legalAddr:

Legal fields

Used in the nested legal object:

Example Request

Using cURL:

curl -X POST https://sandbox.custodia-tech.com/md/api/Companies \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Field Services",
    "externalId": "ERP-ACME-001",
    "website": "https://www.acme.example",
    "dns": ";acme.example;",
    "billingAddress": {
      "houseNumber": "100",
      "street": "Market Street",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "postalCode": "94105",
      "phone": "+1-415-555-0100"
    },
    "legal": {
      "taxId": "12-3456789",
      "legalName": "Acme Field Services Inc.",
      "structure": "CORPORATION",
      "established": "2018-03-15",
      "country": "US",
      "stateOfIncorporation": "DE",
      "industry": "Field Services",
      "isPublic": false
    },
    "legalAddr": {
      "houseNumber": "100",
      "street": "Market Street",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "postalCode": "94105"
    }
  }'

Using JavaScript (fetch):

const response = await fetch('https://sandbox.custodia-tech.com/md/api/Companies', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Field Services',
    externalId: 'ERP-ACME-001',
    dns: ';acme.example;',
    billingAddress: {
      houseNumber: '100',
      street: 'Market Street',
      city: 'San Francisco',
      state: 'CA',
      country: 'US',
      postalCode: '94105',
      phone: '+1-415-555-0100'
    },
    legal: {
      taxId: '12-3456789',
      legalName: 'Acme Field Services Inc.',
      structure: 'CORPORATION',
      established: '2018-03-15',
      country: 'US',
      stateOfIncorporation: 'DE',
      isPublic: false
    }
  })
});

const company = await response.json();

Response

{
  "id": "7332ad13-d460-457d-b73f-0e1681f060fc",
  "name": "Acme Field Services",
  "status": "new",
  "externalId": "ERP-ACME-001",
  "website": "https://www.acme.example",
  "dns": ";acme.example;",
  "license": "enterprise",
  "maxUsers": 50,
  "maxCards": 50,
  "maxAdmins": 5,
  "tenantType": "normal",
  "createdOn": "2026-07-08T02:10:00.000Z"
}

The company starts in new status. Use the returned id as companyId when creating users and configuring the program. Lifecycle status changes (for example to active) are handled by Custodia operations: do not set status directly via partner APIs.

Company Fields (summary)

Error Responses

Related documentation

• Create user: requires companyId from this endpoint
• Spend templates
• Chart of accounts
• Glossary: companyId
• Authentication