API docs by Redocly

Business API (1.0.0)

Download OpenAPI specification:Download

Notice: The /v1.0 endpoints will be deprecated soon. New integrations should use the /v2 endpoints.

Welcome to Delta Defense's API documentation. Use these endpoints to add, update, remove, and fetch your group members.

Delta Defense treats your system as the data source of truth for the members you add. Send a PATCH when a member's personal information changes, and a DELETE when they are no longer a member.

Two versions of the group member endpoints are published here. /v2 is the current version and should be used for all new integrations. /v1.0 remains documented for existing integrations and will be deprecated soon. The two differ most in what they allow while a member's add or remove is still being processed - see Group member status.

Authenticating

Every request must include your API key in the X-Api-Key header. Delta Defense will provide you with your initial key, and you can manage your keys yourself from the partner portal.

Environment Base URL
Sandbox https://bizhub.staging.uscca.cloud
Production https://bizhub.uscca.cloud

API keys are generated for each environment, so a Sandbox API key will not work against Production. Should you need to void an API key or issue a new one, you can do so yourself from the partner portal, or get in touch with technical support at Delta Defense.

An API key identifies exactly one group, and every endpoint is scoped to it.

Formatting conventions

IDs

The externalId property is reserved for you to set your own unique identifier for each group member. It must be unique within your group, is limited to 80 characters, and may be any format you like.

Wherever an endpoint takes an {id} in the path, you may supply either Delta Defense's id for that member or your own externalId. You are not required to store Delta Defense's IDs in your system.

Date-times

All timestamps are returned as YYYY-MM-DD HH:MM:SS - for example 2024-01-25 16:30:59 - in US Central time (America/Chicago). No UTC offset is included in the value.

Addresses

  • country must be USA. US and United States are also accepted.
  • state must be the common two-character abbreviation, e.g. WI. The 50 states plus DC, PR and VI are accepted.
  • postalCode may be five digits (53095) or ZIP+4 (53095-1234).
  • address2 is optional, but send it as "" or omit it entirely - an explicit null fails validation.
  • phone excludes the country code and must be formatted XXX-XXX-XXXX.

USCCA memberships are not available in NY, NJ and WA. Submitting a member located in one of those states is rejected with a 422 - USCCA memberships are not available in the following states: NY, NJ, WA. This applies both when adding a member and when updating their address, on both versions.

Group member status

Because adding and removing members requires processing on Delta Defense's side, a POST does not result in an immediately active USCCA membership for that person. Every group member therefore carries a status field describing where they sit in that process, and a statusUpdatedAt field recording when that status last changed. Both are derived from the member's action records.

Status Meaning
pending-add The request was successfully received to add this person as a group member, and is waiting to be processed.
added The pending-add request has been processed and the group member now has an active membership.
pending-remove The request was successfully received to remove this person as a group member. Their membership will be canceled once the request has been processed.
removed The removal has been processed. You will not normally observe this value: processing a removal also deletes the group member record, after which requests for that member return 404.

In Production, the timing depends on Delta Defense's processing of the request, so a member may sit in pending-add or pending-remove for some time. In the Sandbox environment both are picked up automatically within a few minutes, so you can exercise the full lifecycle without waiting on manual processing.

What you may do while a member is pending

This is the most significant behavioral difference between the two versions.

/v1.0 - while a group member has an unprocessed action, their information may not be updated and no further requests may be taken against the record, except for GET requests. Both PATCH and DELETE return 409 (The group member is in a pending state and cannot be modified.) for pending-add and pending-remove alike, and re-POSTing a member whose removal is pending conflicts on their email rather than reinstating them. A pending member is effectively read-only until Delta Defense has processed the action.

/v2 - the pending block has been removed:

  • PATCH accepts a pending member, and applies the new values to the unprocessed action as well, so a correction made before processing is picked up rather than only taking effect afterward.
  • DELETE against a pending-add cancels it outright and returns 204, since the member was never activated.
  • POST with the same member's details reinstates a member whose removal is still pending. On /v1.0 that request is rejected with a 409 instead.
  • Only a second DELETE against an already-pending removal conflicts.

Group member actions

Actions serve as historical records for requests to add and remove group members. A group member's response includes an actions property sorted with the most recent action first, and the status fields on the group member record are derived from these action records.

An add action carries the member details the request was submitted with; a remove action carries no payload. processedAt is null until Delta Defense has completed the underlying onboarding or offboarding work - it is system controlled and cannot be set through the API.

Errors

Errors are returned as a top-level errors array, each entry carrying a status, title and detail. Always check detail for the specific cause: several distinct conditions share a single status code.

Two of these are header checks that apply to every endpoint on both versions and are enforced before the request is looked at any further: a request that does not send Accept: application/json is rejected with a 406, and a request that sends a body without Content-Type: application/json is rejected with a 415. In both cases nothing is created, updated or removed.

Error Code Meaning
401 Unauthorized - your API credentials are missing or wrong.
404 Not Found - the specified resource could not be found, or belongs to another group.
405 Method Not Allowed - you tried to access a resource with an invalid method.
406 Not Acceptable - the Accept header was missing or was not application/json, which is the only content type the API produces. Applies to every endpoint.
409 Conflict - the request collides with the current state of the record. The causes differ per endpoint and per version; see the individual endpoint for the exact conditions and messages.
415 Unsupported Media Type - the Content-Type header was missing or was not application/json, which is the only format the API accepts. Applies to every request that sends a body (POST and PATCH).
422 Data validation failed (in response to a POST request, for example). Check the response body for the offending field and detailed error message.
500 Internal Server Error - we had a problem with our server. Try again later or contact support.
502 Bad Gateway - a service the USCCA depends on was briefly unavailable. The request was not applied and can be retried unchanged. /v2 only; on /v1.0 the same condition surfaces as a 500.

Group Member (v2)

Manage the members of your group. Delta Defense treats your system as the data source of truth, so PATCH a member when their personal information changes and DELETE them when they are no longer a member.

Adds and removes are recorded as actions that the USCCA processes asynchronously, so a member's status moves through pending-add before settling on added, and through pending-remove until the removal is processed and the record is deleted. Unlike /v1.0, a pending member is not read-only: they can still be updated with PATCH, a still-pending add is cancelled by a subsequent DELETE, and a still-pending remove is cancelled by a subsequent POST with the same details - but a second DELETE while a remove is already pending conflicts instead of repeating it. See POST /v2/group-members and DELETE /v2/group-members/{id}.

Add a group member

Add a group member to the group tied to the supplied API key.

The member is created immediately and returned with status pending-add and a matching unprocessed add action. The USCCA processes that action asynchronously, at which point the member becomes added. While the action is still unprocessed you can correct the submission with PATCH /v2/group-members/{id}, or cancel it outright with DELETE /v2/group-members/{id} - since the member was never activated, that deletes the member along with the action.

If the email already belongs to a member whose removal is still pending (status pending-remove), this is treated as a followup to that removal rather than a new member - provided the submitted externalId also matches that same member. When it does, the pending removal is cancelled and the existing member is reinstated to its prior status and returned with 200, not 201. When it does not - the externalId belongs to no one, or to a different member entirely - the request is rejected with 409 rather than silently resurrecting the member under an unverified identifier. See the 200 and 409 responses below for the exact conditions.

header Parameters
X-Api-Key
required
string
Example: Hpm42xgy.LXu3C15JmnLhyiuwder6vX9DSyEiZ38Y

The API key provided to you by Delta Defense. It identifies exactly one group, and every request is scoped to that group. Keys are generated per environment, so a Sandbox key will not work against Production.

Accept
required
string
Example: application/json

Must be application/json. Required on every request - application/json is the only content type the API produces.

Content-Type
required
string
Example: application/json

Must be application/json. Required on every request that sends a body - application/json is the only content type the API accepts.

Request Body schema: application/json
required
externalId
required
string <= 80 characters

Unique within the group, any format

name
required
string <= 40 characters
surname
required
string <= 80 characters
email
required
string

Must not already belong to another group member

phone
string or null

Country code excluded phone number, format XXX-XXX-XXXX

required
object

Responses

Request samples

Content type
application/json
{
  • "externalId": "2719",
  • "name": "Tim",
  • "surname": "Schmidt",
  • "email": "[email protected]",
  • "phone": "555-555-5555",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Find all group members

Retrieve a paginated list of the group members belonging to the group tied to the supplied API key, optionally narrowed by an exact email and/or phone match. Supplying both requires a member to match both values, not either one.

Only page, perPage, email and phone are accepted; any other query parameter is rejected with a 422.

Each member is returned in full, including their current shipping address and their complete actions history - the same representation you get from GET /v2/group-members/{id}.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page of results to return. Defaults to 1.

perPage
integer [ 1 .. 50 ]
Default: 50
Example: perPage=10

The number of group members to return per page. Defaults to 50, which is also the maximum.

email
string <email>

Return only group members whose email is an exact match. Matching is case insensitive. When combined with phone, a group member must match both values.

phone
string^([0-9]{3})[-]([0-9]{3})[-]([0-9]{4})$
Example: phone=555-555-5555

Return only group members whose phone number is an exact match. Country code excluded, format XXX-XXX-XXXX. When combined with email, a group member must match both values.

header Parameters
X-Api-Key
required
string
Example: Hpm42xgy.LXu3C15JmnLhyiuwder6vX9DSyEiZ38Y

The API key provided to you by Delta Defense. It identifies exactly one group, and every request is scoped to that group. Keys are generated per environment, so a Sandbox key will not work against Production.

Accept
required
string
Example: application/json

Must be application/json. Required on every request - application/json is the only content type the API produces.

Responses

Response samples

Content type
application/json
{
  • "links": {
    },
  • "data": [
    ],
  • "meta": {
    }
}

Find a group member

Retrieve a single group member belonging to the group tied to the supplied API key, including their shipping address and their full actions history.

path Parameters
id
required
string
Example: e4cc5e1a-1240-11eb-9573-0242ac140005

The group member to act on. Accepts Delta Defense's id for the member or your own externalId for them - both resolve to the same record, so you are not required to store Delta Defense's IDs in your system.

Only members of the group tied to the supplied API key can be resolved; a member belonging to another group returns 404.

header Parameters
X-Api-Key
required
string
Example: Hpm42xgy.LXu3C15JmnLhyiuwder6vX9DSyEiZ38Y

The API key provided to you by Delta Defense. It identifies exactly one group, and every request is scoped to that group. Keys are generated per environment, so a Sandbox key will not work against Production.

Accept
required
string
Example: application/json

Must be application/json. Required on every request - application/json is the only content type the API produces.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a group member

Update a group member belonging to the group tied to the supplied API key. Only the fields present in the request body are changed.

Unlike PATCH /v1.0/group-members/{id}, this endpoint also accepts members in a pending state. When the member still has an unprocessed action, the new values are applied to that action's data as well, so a correction made before the USCCA processes the action is picked up rather than being applied only after the fact.

processedAt is system controlled. It is stripped from the request body if supplied, so a caller can never mark their own action as processed.

Changing email to an address already in use by another account returns a 409.

path Parameters
id
required
string
Example: e4cc5e1a-1240-11eb-9573-0242ac140005

The group member to act on. Accepts Delta Defense's id for the member or your own externalId for them - both resolve to the same record, so you are not required to store Delta Defense's IDs in your system.

Only members of the group tied to the supplied API key can be resolved; a member belonging to another group returns 404.

header Parameters
X-Api-Key
required
string
Example: Hpm42xgy.LXu3C15JmnLhyiuwder6vX9DSyEiZ38Y

The API key provided to you by Delta Defense. It identifies exactly one group, and every request is scoped to that group. Keys are generated per environment, so a Sandbox key will not work against Production.

Accept
required
string
Example: application/json

Must be application/json. Required on every request - application/json is the only content type the API produces.

Content-Type
required
string
Example: application/json

Must be application/json. Required on every request that sends a body - application/json is the only content type the API accepts.

Request Body schema: application/json
required
externalId
string <= 80 characters

Unique within the group, any format

name
string <= 40 characters
surname
string <= 80 characters
email
string
phone
string or null

Country code excluded phone number, format XXX-XXX-XXXX

object

When address is supplied, every field other than address2 is required.

Responses

Request samples

Content type
application/json
{
  • "externalId": "2719",
  • "name": "Tim",
  • "surname": "Schmidt",
  • "email": "[email protected]",
  • "phone": "555-555-5555",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Remove a group member

Remove a group member from the group tied to the supplied API key. What happens depends on the member's current state:

  • No pending action. Records a remove action rather than deleting the member outright, and returns the updated member with status pending-remove (200). The USCCA processes the removal asynchronously, at which point the member becomes removed.
  • A pending add. The add was never actually processed, so this cancels it outright instead of queuing a removal on top of it - the member and the pending action are both deleted (204, no body).
  • A remove already pending. A second remove action is not created - this returns 409, since a duplicate call has nothing new to do and the first removal hasn't finished yet.

To undo a still-pending removal, call POST /v2/group-members again with the same member's details; the removal is cancelled and the existing member is reinstated. On /v1.0 that request is rejected with a 409 instead.

path Parameters
id
required
string
Example: e4cc5e1a-1240-11eb-9573-0242ac140005

The group member to act on. Accepts Delta Defense's id for the member or your own externalId for them - both resolve to the same record, so you are not required to store Delta Defense's IDs in your system.

Only members of the group tied to the supplied API key can be resolved; a member belonging to another group returns 404.

header Parameters
X-Api-Key
required
string
Example: Hpm42xgy.LXu3C15JmnLhyiuwder6vX9DSyEiZ38Y

The API key provided to you by Delta Defense. It identifies exactly one group, and every request is scoped to that group. Keys are generated per environment, so a Sandbox key will not work against Production.

Accept
required
string
Example: application/json

Must be application/json. Required on every request - application/json is the only content type the API produces.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Group Member (v1)

Will be deprecated soon. Use the /v2 group member endpoints instead.

These endpoints add, update, remove and fetch group members as /v2 does, with two notable differences: there is no endpoint for listing all group members, and a member with an unprocessed action is read-only. While a member is pending-add or pending-remove, PATCH and DELETE both return 409 until Delta Defense has processed the pending action, and a pending removal cannot be reinstated by re-POSTing the member. See What you may do while a member is pending.

Add a group member

Deprecation notice: This /v1.0 endpoint will be deprecated soon. New integrations should use POST /v2/group-members.

Add a group member to the group tied to the supplied API key.

Because adds require processing on Delta Defense's side, this does not result in an immediately active USCCA membership for the given person. The member is created and returned with status pending-add and a matching unprocessed add action; they become added once Delta Defense has processed that action.

While the add is still pending, the member is read-only on /v1.0 - PATCH and DELETE both return 409 until the action has been processed. PATCH /v2/group-members/{id} and DELETE /v2/group-members/{id} accept pending members, so use /v2 if you need to correct or cancel a submission before it is processed.

externalId is your own identifier for the member. It is required, must be unique within your group, and can be used in place of Delta Defense's id in the path of the other group member endpoints.

Re-adding a member whose removal is still pending is not supported here: that member still exists, so the request conflicts with their existing record. POST /v2/group-members reinstates such a member instead of conflicting.

header Parameters
X-Api-Key
required
string
Example: Hpm42xgy.LXu3C15JmnLhyiuwder6vX9DSyEiZ38Y

The API key provided to you by Delta Defense. It identifies exactly one group, and every request is scoped to that group. Keys are generated per environment, so a Sandbox key will not work against Production.

Accept
required
string
Example: application/json

Must be application/json. Required on every request - application/json is the only content type the API produces.

Content-Type
required
string
Example: application/json

Must be application/json. Required on every request that sends a body - application/json is the only content type the API accepts.

Request Body schema: application/json
required
externalId
required
string <= 80 characters

Your own identifier for this group member. Unique within the group, any format. Can be used in place of Delta Defense's id in the path of the other group member endpoints.

name
required
string <= 40 characters
surname
required
string <= 80 characters
email
required
string

Must not already belong to another group member, including one whose add or remove is still pending

phone
string or null

Country code excluded phone number, format XXX-XXX-XXXX

required
object

Responses

Request samples

Content type
application/json
{
  • "externalId": "2719",
  • "name": "Tim",
  • "surname": "Schmidt",
  • "email": "[email protected]",
  • "phone": "555-555-5555",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Find a group member

Deprecation notice: This /v1.0 endpoint will be deprecated soon. New integrations should use GET /v2/group-members/{id}.

Retrieve a single group member belonging to the group tied to the supplied API key, including their address and their full actions history.

GET is the only request accepted against a group member while they have an unprocessed action, so this is how you follow a pending add or remove to completion: poll the member and watch status and statusUpdatedAt, or the processedAt timestamp on their most recent action.

Note that once a removal has been processed the group member record is deleted, so a member you previously removed returns 404 rather than a record with status removed.

path Parameters
id
required
string
Example: e4cc5e1a-1240-11eb-9573-0242ac140005

The group member to act on. Accepts Delta Defense's id for the member, your own externalId for them, or their userId - all three resolve to the same record, so you are not required to store Delta Defense's IDs in your system.

Only members of the group tied to the supplied API key can be resolved; a member belonging to another group returns 404.

header Parameters
X-Api-Key
required
string
Example: Hpm42xgy.LXu3C15JmnLhyiuwder6vX9DSyEiZ38Y

The API key provided to you by Delta Defense. It identifies exactly one group, and every request is scoped to that group. Keys are generated per environment, so a Sandbox key will not work against Production.

Accept
required
string
Example: application/json

Must be application/json. Required on every request - application/json is the only content type the API produces.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a group member

Deprecation notice: This /v1.0 endpoint will be deprecated soon. New integrations should use PATCH /v2/group-members/{id}.

Update a group member belonging to the group tied to the supplied API key. Only the fields present in the request body are changed.

Delta Defense treats your system as the data source of truth for the members you add, so send a PATCH whenever a member's personal information changes.

A group member with an unprocessed action cannot be updated. While their status is pending-add or pending-remove, this endpoint returns 409 and the update has to wait until Delta Defense has processed the pending action. PATCH /v2/group-members/{id} lifts this restriction, and additionally applies the new values to the pending action itself so a correction made before processing is picked up rather than only taking effect afterward.

Updating address is subject to the same state restrictions as adding a member: NY, NJ and WA are rejected with a 422.

path Parameters
id
required
string
Example: e4cc5e1a-1240-11eb-9573-0242ac140005

The group member to act on. Accepts Delta Defense's id for the member, your own externalId for them, or their userId - all three resolve to the same record, so you are not required to store Delta Defense's IDs in your system.

Only members of the group tied to the supplied API key can be resolved; a member belonging to another group returns 404.

header Parameters
X-Api-Key
required
string
Example: Hpm42xgy.LXu3C15JmnLhyiuwder6vX9DSyEiZ38Y

The API key provided to you by Delta Defense. It identifies exactly one group, and every request is scoped to that group. Keys are generated per environment, so a Sandbox key will not work against Production.

Accept
required
string
Example: application/json

Must be application/json. Required on every request - application/json is the only content type the API produces.

Content-Type
required
string
Example: application/json

Must be application/json. Required on every request that sends a body - application/json is the only content type the API accepts.

Request Body schema: application/json
required
externalId
string <= 80 characters

Your own identifier for this group member. Unique within the group, any format.

name
string <= 40 characters
surname
string <= 80 characters
email
string

Must not already be linked to an existing USCCA account, or the request is rejected with a 409

phone
string or null

Country code excluded phone number, format XXX-XXX-XXXX

object

When address is supplied, every field other than address2 is required.

Responses

Request samples

Content type
application/json
{
  • "externalId": "2719",
  • "name": "Tim",
  • "surname": "Schmidt",
  • "email": "[email protected]",
  • "phone": "555-555-5555",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Remove a group member

Deprecation notice: This /v1.0 endpoint will be deprecated soon. New integrations should use DELETE /v2/group-members/{id}.

Remove a group member from the group tied to the supplied API key. Delta Defense treats your system as the data source of truth for the members you add, so send a DELETE once a person is no longer one of your members.

This records a remove action rather than deleting the member outright, and returns the member with status pending-remove. Removals are processed manually by a Delta Defense employee; once processed, the person's membership is canceled and their group member record is deleted, after which requests for that member return 404.

A group member with an unprocessed action cannot be removed. This returns 409 for pending-add and pending-remove alike, which means a pending add cannot be cancelled on /v1.0 - it has to be processed first, and the member removed afterward. DELETE /v2/group-members/{id} cancels a pending add outright instead, returning 204.

There is also no way to undo a pending removal on /v1.0: re-adding the member conflicts on their email address until the removal has been processed. POST /v2/group-members reinstates such a member instead.

path Parameters
id
required
string
Example: e4cc5e1a-1240-11eb-9573-0242ac140005

The group member to act on. Accepts Delta Defense's id for the member, your own externalId for them, or their userId - all three resolve to the same record, so you are not required to store Delta Defense's IDs in your system.

Only members of the group tied to the supplied API key can be resolved; a member belonging to another group returns 404.

header Parameters
X-Api-Key
required
string
Example: Hpm42xgy.LXu3C15JmnLhyiuwder6vX9DSyEiZ38Y

The API key provided to you by Delta Defense. It identifies exactly one group, and every request is scoped to that group. Keys are generated per environment, so a Sandbox key will not work against Production.

Accept
required
string
Example: application/json

Must be application/json. Required on every request - application/json is the only content type the API produces.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}