Table of Contents |
---|
Introduction
The CardExchange Cloud API is organized around REST. The API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
You can use the CardExchange Cloud API in test mode, which does not affect your live data. The API key you use to authenticate the request determines whether the request is live mode or test mode.
Authentication
The CardExchange Cloud API uses API keys to authenticate requests. You can view your API keys on the profile page of the CardExchange Cloud Auth website.
...
If you need to authenticate via bearer auth (e.g., for a cross-origin request), use the Bearer auth header instead.
Errors
CardExchange Cloud uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, an invalid value was supplied, etc.). Codes in the 5xx range indicate an error with the CardExchange Cloud server.
...
title | string | A short, human-readable summary of the problem type. |
status | integer | The HTTP status code generated by the server for this occurrence of the problem. |
detail | string | A human-readable explanation specific to this occurrence of the problem. |
errors | object | Set of key-value pairs providing more details about the error. If the error is parameter-specific, the key will contain the parameter related to the error. Otherwise, the key will be an empty string. |
Addresses
Address objects contain information about a person's physical mailing address.
The address object
Attributes
id | string(guid) | Unique identifier for the object. |
person | string(guid) | ID of the person who the address belongs to. |
type | string | Address type. One of: home, business, or po_box. |
streetAddress | string | Full street address component, which may include house number, street name, Post Office Box, and multi-line extended street address information. |
locality | string | City or locality component. |
region | string | State, province, prefecture, or region component. |
postalCode | string | Zip code or postal code component. |
country | string | Country name component. |
metadata | object | Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. |
created | string(date-time) | Time at which the object was created. |
Create an address
Creates a new address object.
...
Returns an address object if the call succeeded.
Retrieve an address
Retrieves the details of an existing address.
...
Returns an address object if a valid identifier was provided.
Update an address
Updates the specified address.
...
Returns the address object if the update succeeded. Returns an error if update parameters are invalid (e.g. specifying an invalid type or an invalid person).
Delete an address
Permanently deletes an address. It cannot be undone.
...
Returns an empty response on success. If the address ID does not exist, this call returns an error.
List all addresses
Returns a list of addresses.
...
A list of up to per_page addresses, starting at page. Passing the optional search query will result in filtering to only addresses that mention the supplied value. Passing any of the optional filters will result in filtering to addresses with only those exact values. Each entry in the list is a separate address object. If no more addresses are available, the resulting list will be empty. The response will contain two extra headers, Link and X-Total-Count, which provide convenience URLs to the first, last, next, and/or previous pages, and the total number of objects based on the supplied search criteria.
Anonymous sets
Anonymous set objects represent a set of cardholders and cards that are not linked to a real person. The associated anonymous cardholders can be linked to real persons as visitors or temporary cardholders.
The anonymous set object
Attributes
id | string(guid) | Unique identifier for the object. |
profile | string(guid) | ID of the cardholder profile associated with the anonymous set. |
defaultName | string | Name of the set. |
data | list, contains: person object | Anonymous cardholders and cards contained in the set. |
Create an anonymous set
Creates a new set of anonymous cardholders and cards.
...
Returns an anonymous set object if the call succeeded.
Retrieve an anonymous set
Retrieves the details of an existing anonymous set.
...
Returns an anonymous set object if a valid identifier was provided.
Update an anonymous set
Adds additional cards to the specified anonymous set.
...
Returns the anonymous set object if the update succeeded. Returns an error if update parameters are invalid (e.g. specifying a quantity less than 1 or an invalid department).
Delete an anonymous set
Since cards cannot be deleted, anonymous sets cannot be deleted either.
List all anonymous sets
Returns a list of anonymous sets.
...
A list of up to per_page anonymous sets, starting at page. Passing the optional search query will result in filtering to only sets that mention the supplied value. Passing any of the optional filters will result in filtering to sets with only those exact values. Each entry in the list is a separate anonymous set object. If no more sets are available, the resulting list will be empty. The response will contain two extra headers, Link and X-Total-Count, which provide convenience URLs to the first, last, next, and/or previous pages, and the total number of objects based on the supplied search criteria.
Cardholders
Cardholder objects contain information about a person's profile and contain the cards that belong to the profile.
The cardholder object
Attributes
id | string(guid) | Unique identifier for the object. |
person | string(guid) | ID of the person who the cardholder belongs to. |
profile | object | Object describing the cardholder's profile. |
profileNumber | string | Unique, displayable identifier for the cardholder. |
loginId | string | Username for the profile. |
string | Email for the profile. | |
businessUnit | object | Object describing the cardholder's business unit. |
externalCompany | object | Object describing the cardholder's external company. |
department | object | Object describing the cardholder's department. |
costAccount | object | Object describing the cardholder's cost account. |
location | object | Object describing the cardholder's location. |
startDate | string(date-time) | Start date of the cardholder. |
endDate | string(date-time) | End date of the cardholder. |
status | string | Status of the cardholder. One of: activated, blocked, expired, blacklisted, linked, or unlinked. |
nameOnCard | string | Name that will be displayed on the cards for the cardholder. |
note | string | Additional notes for the cardholder. |
metadata | object | Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. |
created | string(date-time) | Time at which the object was created. |
cards | list, contains: card object | List of cards belonging to the cardholder. |
Create a cardholder
Creates a new cardholder object.
...
Returns a cardholder object if the call succeeded.
Retrieve a cardholder
Retrieves the details of an existing cardholder.
...
Returns a cardholder object if a valid identifier was provided.
Update a cardholder
Updates the specified cardholder.
...
Returns the cardholder object if the update succeeded. Returns an error if update parameters are invalid (e.g. specifying an invalid email or an invalid status).
Delete a cardholder
Permanently deletes a cardholder. It cannot be undone.
...
Returns an empty response on success. If the cardholder ID does not exist, this call returns an error.
List all cardholders
Returns a list of cardholders.
...
A list of up to per_page cardholders, starting at page. Passing the optional search query will result in filtering to only cardholders that mention the supplied value. Passing any of the optional filters will result in filtering to cardholders with only those exact values. Each entry in the list is a separate cardholder object. If no more cardholders are available, the resulting list will be empty. The response will contain two extra headers, Link and X-Total-Count, which provide convenience URLs to the first, last, next, and/or previous pages, and the total number of objects based on the supplied search criteria.
Cards
Card objects contain information about a physical card that can be used for access control.
The card object
Attributes
id | string(guid) | Unique identifier for the object. |
cardholder | string(guid) | ID of the cardholder that the card belongs to. |
cardNumber | string | Unique, displayable identifier for the card. |
chipserialNumber | string | Chip serial number of the card. |
status | string | Status of the card. One of: initialized, in_production, personalized, withdrawn, activated, blocked, expired, blacklisted, issued, returned, destroyed, bulk_blocked, linked, or unlinked. |
type | object | Object describing the card's type. |
encryption | string | Encryption method used for the card. One of: aes, des, or triple_des. |
layout | object | Object describing the card's layout. |
startDate | string(date-time) | Start date of the card. |
endDate | string(date-time) | End date of the card. |
pickupNotice | boolean | Currently not used. |
metadata | object | Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. |
created | string(date-time) | Time at which the object was created. |
Create a card
Creates a new card object.
...
Returns a card object if the call succeeded.
Retrieve a card
Retrieves the details of an existing card.
...
Returns a card object if a valid identifier was provided.
Update a card
Updates the specified card.
...
Returns the card object if the update succeeded. Returns an error if update parameters are invalid (e.g. specifying an invalid status or invalid metadata).
Delete a card
Cards cannot be deleted.
List all cards
Returns a list of cards.
Action URL
...
A list of up to per_page cards, starting at page. Passing the optional search query will result in filtering to only cards that mention the supplied value. Passing any of the optional filters will result in filtering to cards with only those exact values. Each entry in the list is a separate card object. If no more cards are available, the resulting list will be empty. The response will contain two extra headers, Link and X-Total-Count, which provide convenience URLs to the first, last, next, and/or previous pages, and the total number of objects based on the supplied search criteria.
Persons
Person objects contain basic information about a person.
The person object
Attributes
id | string(guid) | Unique identifier for the object. |
personNumber | string | Unique, displayable identifier for the person. |
profile | string(guid) | ID of the person's profile. |
addressPreference | string | Person's preferred address type. One of: home, business, or po_box. |
identificationType | string | Person's preferred method of identification. One of: none, driver_license, passport, eu, or foreigner. |
identificationTypeValue | string | Value for the person's specified identification method. |
firstName | string | First name of the person. |
middleName | string | Middle name of the person. |
lastName | string | Last name of the person. |
birthDate | string(date) | Person's birthday, represented as an ISO 8601:2004 YYYY-MM-DD format. |
gender | string | Person's gender. One of: not_specified, female, male, other, or decline. |
prefix | string | Person's name prefix. One of: none, dr, mr, mrs, or ms. |
suffix | string | Person's name suffix. One of: none, ii, iii, iv, jr, md, phd, or sr. |
phoneNumber | string | Person's preferred telephone number. E.164 is recommended as the format of this value, for example, +1 (425) 555-1212 or +56 (2) 687 2400. |
mobileNumber | string | Person's preferred mobile number. E.164 is recommended as the format of this value, for example, +1 (425) 555-1212 or +56 (2) 687 2400. |
status | string | Status of the person. One of: none, activated, blocked, expired, blacklisted, linked, or unlinked. |
metadata | object | Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. |
photo | string(base-64) | Person's photo. |
created | string(date-time) | Time at which the object was created. |
addresses | list, contains: address object | List of the person's addresses. |
cardholders | list, contains: cardholder object | List of cardholders belonging to the person. |
Create a person
Creates a new person object.
...
Returns a person object if the call succeeded.
Retrieve a person
Retrieves the details of an existing person.
...
Returns a person object if a valid identifier was provided.
Update a person
Updates the specified person.
...
Returns the person object if the update succeeded. Returns an error if update parameters are invalid (e.g. specifying an invalid identification method or not specifying a birthday).
Delete a person
Permanently deletes a person. It cannot be undone.
...
Returns an empty response on success. If the person ID does not exist, this call returns an error.
List all persons
Returns a list of persons.
...
A list of up to per_page persons, starting at page. Passing the optional search query will result in filtering to only persons that mention the supplied value. Passing any of the optional filters will result in filtering to persons with only those exact values. Each entry in the list is a separate person object. If no more persons are available, the resulting list will be empty. The response will contain two extra headers, Link and X-Total-Count, which provide convenience URLs to the first, last, next, and/or previous pages, and the total number of objects based on the supplied search criteria.
Productions
Production objects contain information related to the production of a single card.
The production object
Attributes
id | string(guid) | Unique identifier for the object. |
person | string(guid) | ID of the person associated with the production. |
cardholder | string(guid) | ID of the cardholder associated with the production. |
card | string(guid) | ID of the card associated with the production. |
nameOnCard | string | Name that will be displayed on the card. |
chipserialNumber | string | Chip serial number of the card. |
userName | string | User who initiated the card production process. |
exported | boolean | Indicates whether the card has been exported. |
printedOn | string(date-time) | Date the card was printed. |
numberOfTries | integer | Number of tries needed to successfully print the card. |
Create a production
Production records cannot be manually created. They are automatically created when a card enters the 'in production' state.
Retrieve a production
Retrieves the details of an existing production record.
...
Returns a production object if a valid identifier was provided.
Update a production
Updates the specified production record.
...
Returns the production object if the update succeeded. Returns an error if update parameters are invalid (e.g. specifying an invalid number of tries or an invalid date).
Delete a production
Production records cannot be manually deleted. They are automatically deleted when a card leaves the 'in production' state.
List all productions
Returns a list of production records.
...