Users

Overview

The Users endpoints allow you to create new users, update existing user information, and order cards for users. This guide applies to both agentic payments and white label integrations. All endpoints require authentication using a Bearer token obtained from the authentication endpoint.

Create User

Creates a new user in the system. The user will be associated with the company specified in the request.

Request Body

Example Request

Using cURL:

curl -X POST https://sandbox.custodia-tech.com/md/api/User \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "John",
    "lastname": "Doe",
    "email": "john.doe@example.com",
    "companyId": "your-company-id",
    "mobile": "+15551234567",
    "address": "123 Example Street, Example City, 10001, US",
    "active": true,
    "reason": "active",
    "emailVerified": true
  }'

Using JavaScript (fetch):

const response = await fetch('https://sandbox.custodia-tech.com/md/api/User', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    firstname: 'John',
    lastname: 'Doe',
    email: 'john.doe@example.com',
    companyId: 'your-company-id',
    mobile: '+15551234567',
    address: '123 Example Street, Example City, 10001, US',
    active: true,
    reason: 'active',
    emailVerified: true
  })
});

const user = await response.json();

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "firstname": "John",
  "lastname": "Doe",
  "email": "john.doe@example.com",
  "companyId": "your-company-id",
  "mobile": "+15551234567",
  "address": "123 Example Street, Example City, 10001, US",
  "active": true,
  "reason": "active",
  "emailVerified": true,
  "created": "2024-01-15T10:30:00.000Z",
  "modified": "2024-01-15T10:30:00.000Z"
}

Update User

Updates an existing user's information. Only include the fields you want to update in the request body. Use PATCH to add or correct mobile and address before ordering a card if either was missing at create time.

Path Parameters

Request Body

Include only the fields you want to update. All fields are optional.

Example Request

Using cURL:

curl -X PATCH https://sandbox.custodia-tech.com/md/api/User/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "Jane",
    "mobile": "+15559876543",
    "address": "456 Sample Avenue, Sample City, 10002, US"
  }'

Using JavaScript (fetch):

const userId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/User/${userId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    firstname: 'Jane',
    mobile: '+15559876543',
    address: '456 Sample Avenue, Sample City, 10002, US'
  })
});

const updatedUser = await response.json();

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "firstname": "Jane",
  "lastname": "Doe",
  "email": "john.doe@example.com",
  "mobile": "+15559876543",
  "address": "456 Sample Avenue, Sample City, 10002, US",
  "modified": "2024-01-15T11:00:00.000Z"
}

Search User Cards

Searches users and returns card status data for each matched user. This endpoint is useful when you need to find users by email or text and inspect their card access in the same request.

Request Body

Common User Filters (filter)

Common Card Filters (cardsFilter)

Example Request

Using cURL:

curl -X POST https://sandbox.custodia-tech.com/md/api/User/cards-status \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "searchTerm": "user@example.com",
      "fields": {
        "id": true,
        "email": true
      }
    },
    "cardsFilter": {
      "multiple": true,
      "where": {
        "state": { "inq": ["ACTIVE"] },
        "cardProductId": "your card product Id"
      },
      "otherCardsFilter": {},
      "fields": {
        "id": true,
        "ownerId": true,
        "cardNo": true,
        "state": true,
        "cardType": true,
        "vendor": true,
        "cardProductId": true
      }
    }
  }'

Using JavaScript (fetch):

const response = await fetch('https://sandbox.custodia-tech.com/md/api/User/cards-status', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filter: {
      searchTerm: 'user@example.com',
      fields: {
        id: true,
        email: true
      }
    },
    cardsFilter: {
      multiple: true,
      where: {
        state: {inq: ['ACTIVE']},
        cardProductId: 'your card product Id'
      },
      otherCardsFilter: {},
      fields: {
        id: true,
        ownerId: true,
        cardNo: true,
        state: true,
        cardType: true,
        vendor: true,
        cardProductId: true
      }
    }
  })
});

const usersWithCards = await response.json();

Response

[
  {
    "id": "297e880a-07f6-4817-b7f0-c9d172329748",
    "email": "user@example.com",
    "card": {
      "cardId": "2358fb0c-1298-4300-b596-4aef822b2959",
      "ownerId": "297e880a-07f6-4817-b7f0-c9d172329748",
      "cardNo": "6221",
      "state": "ACTIVE",
      "cardType": "virtual",
      "vendor": "card vendor"
    },
    "cards": [
      {
        "cardId": "35b07f7e-244f-4f69-a3a6-1a58be6f61b1",
        "ownerId": "297e880a-07f6-4817-b7f0-c9d172329748",
        "cardNo": "1044",
        "state": "ACTIVE",
        "cardType": "physical",
        "vendor": "card vendor"
      }
    ]
  }
]

Order Card for User

Orders a new card for a user. The card will be associated with a card product. If no card product is specified, the system will use the default card product for the user's company.

Path Parameters

Request Body

Instructions Object

The instructions object can contain the following optional fields:

Example Request

Using cURL:

curl -X POST https://sandbox.custodia-tech.com/md/api/User/550e8400-e29b-41d4-a716-446655440000/order-card \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "cardProductId": "card-product-id",
    "instructions": {
      "address2use": "user",
      "expedite": false
    }
  }'

Using JavaScript (fetch):

const userId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/User/${userId}/order-card`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    cardProductId: 'card-product-id',
    instructions: {
      address2use: 'user',
      expedite: false
    }
  })
});

const card = await response.json();

Ordering with default card product (no cardProductId):

Using JavaScript (fetch):

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/User/${userId}/order-card`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    instructions: {
      address2use: 'user'
    }
  })
});

const cardDefaultProduct = await response.json();

Response

{
  "id": "card-id-123",
  "ownerId": "550e8400-e29b-41d4-a716-446655440000",
  "cardProductId": "card-product-id",
  "cardNo": "****1234",
  "state": "UNACTIVATED",
  "cardType": "physical",
  "created": "2024-01-15T12:00:00.000Z"
}

Terminate Card

Terminates (cancels) a card for a user. Once terminated, the card cannot be used for transactions. This action is typically irreversible.

Path Parameters

Request Body

Example Request

Using cURL:

curl -X POST https://sandbox.custodia-tech.com/md/api/User/550e8400-e29b-41d4-a716-446655440000/terminate-card \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "pan": "1234",
    "reasonCode": "01",
    "reason": "Card lost - requested by user",
    "issuer": "card issuer"
  }'

Using JavaScript (fetch):

const userId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/User/${userId}/terminate-card`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    pan: '1234',
    reasonCode: '01',
    reason: 'Card lost - requested by user',
    issuer: 'card issuer'
  })
});

const terminatedCard = await response.json();

Terminating with default issuer (card issuer):

Using JavaScript (fetch):

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/User/${userId}/terminate-card`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    pan: '1234',
    reasonCode: '01',
    reason: 'Requested by admin'
  })
});

const terminatedCardDefaultIssuer = await response.json();

Response

{
  "id": "card-id-123",
  "ownerId": "550e8400-e29b-41d4-a716-446655440000",
  "cardNo": "****1234",
  "state": "TERMINATED",
  "cardType": "physical",
  "vendor": "card vendor",
  "terminatedOn": "2024-01-15T14:00:00.000Z"
}

Error Responses

All endpoints may return the following error responses: