Creating Cases

A Case represents a customer you want to verify. Creating a Case sets up the verification and generates the guided flow you complete to onboard a client. When the Case is finished, we send you a case.completed webhook.

POST Create a Case

---

API

Description: Create a new Case for a Client.

Endpoint: POST /integrations/core/cases

Authenticate the request with your Access Token in the X-Workflow-Access-Key header (see Authentication & Setup).

The request body has two top-level objects, both required: activity (the Case itself) and client (the person being verified).

The activity object

Property	Type	Required	Notes
name	String	yes	A name for the Case. Max 50 characters.
nature	String	yes	Free-text description of the nature/purpose of the Case (e.g. "New customer onboarding"). Max 500 characters.
external_id	String	no	Your own reference for the Case. Required if you want to receive the case.completed webhook — see the note below.
max_transaction_value	Number	no	Expected maximum transaction value. Must be greater than 0 if provided.
status	String	no	Defaults to in_progress. One of: in_progress, in_review, on_hold, to_do, completed, cancelled. You will normally omit this.
address_attributes	Object	no	The Case address. See below.

activity.address_attributes object — optional. If you include it, country_code, address_line_1, state and postcode are required.

Property	Type	Required	Notes
country_code	String	yes	ISO 3166-1 alpha-3 code, e.g. "NZL", "AUS". Max 3 characters.
address_line_1	String	yes	Max 128 characters.
state	String	yes	Max 128 characters.
postcode	String	yes	2–16 characters; letters, digits, spaces and hyphens.
address_line_2	String	no	Max 128 characters.
suburb	String	no	Max 128 characters.

The client object

Property	Type	Required	Notes
name	String	yes	The Client's display name. Max 50 characters.
client_type	String	yes	The type of Client. Use individual for a person. Also accepted: company, trust, charity, estate, society, joint.
email	String	no	Must be a valid email address. Max 128 characters.
external_id	String	no	Your own reference for the Client. If a Client with this external_id already exists for your company, that existing Client is reused (and client_type / clientable_attributes are ignored).
clientable_attributes	Object	conditional	The Client's details. Required when creating a new individual (see below).
contact_phone_attributes	Object	no	The Client's contact phone. See below.

client.clientable_attributes object (for an individual)

Property	Type	Required	Notes
firstname	String	yes	Required for an individual.
lastname	String	yes	Required for an individual.
middle_name	String	no
date_of_birth	String	no	ISO 8601 date, e.g. "1990-01-15".

client.contact_phone_attributes object — optional. If you include it, both fields are required.

Property	Type	Required	Notes
phone_country_code	String	yes	Country dialling code, in digits, e.g. "64" (New Zealand) or "61" (Australia). A leading + is accepted.
phone_number	String	yes	National phone number, e.g. "210123456". A leading 0 is removed automatically.

NOTE

external_id is important. The case.completed webhook is only sent for Cases that were created with an activity.external_id. Set it to your system's reference for the Case so you can match the webhook back to your own records. Likewise, client.external_id lets you reuse an existing Client across multiple Cases.

Example request:

cURL

curl https://api.workflow.aplyid.com/integrations/core/cases \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Workflow-Access-Key: YOUR_ACCESS_TOKEN" \
  -d '{
    "activity": {
      "name": "Onboarding — John Doe",
      "nature": "New customer onboarding",
      "max_transaction_value": 50000,
      "external_id": "order-9281",
      "address_attributes": {
        "country_code": "NZL",
        "address_line_1": "22 Pollen Street",
        "suburb": "Grey Lynn",
        "state": "Auckland",
        "postcode": "1021"
      }
    },
    "client": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "external_id": "cust-4471",
      "client_type": "individual",
      "clientable_attributes": {
        "firstname": "John",
        "lastname": "Doe",
        "date_of_birth": "1990-01-15"
      },
      "contact_phone_attributes": {
        "phone_number": "210123456",
        "phone_country_code": "64"
      }
    }
  }'

JavaScript

const response = await fetch(
  "https://api.workflow.aplyid.com/integrations/core/cases",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Workflow-Access-Key": "YOUR_ACCESS_TOKEN",
    },
    body: JSON.stringify({
      activity: {
        name: "Onboarding — John Doe",
        nature: "New customer onboarding",
        max_transaction_value: 50000,
        external_id: "order-9281",
        address_attributes: {
          country_code: "NZL",
          address_line_1: "22 Pollen Street",
          suburb: "Grey Lynn",
          state: "Auckland",
          postcode: "1021",
        },
      },
      client: {
        name: "John Doe",
        email: "john.doe@example.com",
        external_id: "cust-4471",
        client_type: "individual",
        clientable_attributes: {
          firstname: "John",
          lastname: "Doe",
          date_of_birth: "1990-01-15",
        },
        contact_phone_attributes: {
          phone_number: "210123456",
          phone_country_code: "64",
        },
      },
    }),
  },
);

const data = await response.json();

Sample response: 201 Created

{
  "case_id": 1024,
  "external_id": "order-9281",
  "guided_flow_id": 5567,
  "status": "in_progress",
  "case_url": "https://workflow.aplyid.com/guided_flows/standard/5567?position=1",
  "client": {
    "id": 8843,
    "external_id": "cust-4471",
    "name": "John Doe",
    "approval_status": "no_decision_yet"
  }
}

Response fields:

Property	Type	Notes
case_id	Integer	APLYiD's identifier for the Case.
external_id	String / null	The reference you supplied on the activity.
guided_flow_id	Integer	Identifier for the guided flow generated for this Case.
status	String	The Case status (e.g. in_progress).
case_url	String	A link to the Case's guided flow in the APLYiD app.
client	Object	The Client attached to the Case.
client.id	Integer	APLYiD's identifier for the Client.
client.external_id	String / null	The reference you supplied on the client.
client.name	String	The Client's display name.
client.approval_status	String	The Client's verification outcome: approved, denied, or no_decision_yet. Newly created Cases start as no_decision_yet.

Error responses

Errors are returned as JSON with a human-readable message and an APLYiD code.

401 Unauthorized

// Missing or invalid X-Workflow-Access-Key
{
  "message": "Unauthorized"
}

400 Bad Request

// The activity or client object is missing
{
  "message": "param is missing or the value is empty: Client must exist",
  "code": "APLY-400"
}

422 Unprocessable Content

// A field failed validation
{
  "message": "Name can't be blank",
  "code": "APLY-422"
}

422 Unprocessable Content

// client_type is not one of the accepted values
{
  "message": "Invalid client type: organisation",
  "code": "APLY-422"
}