Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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.

...

titlestringA short, human-readable summary of the problem type.
statusintegerThe HTTP status code generated by the server for this occurrence of the problem.
detailstringA human-readable explanation specific to this occurrence of the problem.
errorsobjectSet 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

idstring(guid)Unique identifier for the object.
personstring(guid)ID of the person who the address belongs to.
typestringAddress type. One of: home, business, or po_box.
streetAddressstringFull street address component, which may include house number, street name, Post Office Box, and multi-line extended street address information.
localitystringCity or locality component.
regionstringState, province, prefecture, or region component.
postalCodestringZip code or postal code component.
countrystringCountry name component.
metadataobjectSet 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.
createdstring(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

idstring(guid)Unique identifier for the object.
profilestring(guid)ID of the cardholder profile associated with the anonymous set.
defaultNamestringName of the set.
datalist, contains: person objectAnonymous 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

idstring(guid)Unique identifier for the object.
personstring(guid)ID of the person who the cardholder belongs to.
profileobjectObject describing the cardholder's profile.
profileNumberstringUnique, displayable identifier for the cardholder.
loginIdstringUsername for the profile.
emailstringEmail for the profile.
businessUnitobjectObject describing the cardholder's business unit.
externalCompanyobjectObject describing the cardholder's external company.
departmentobjectObject describing the cardholder's department.
costAccountobjectObject describing the cardholder's cost account.
locationobjectObject describing the cardholder's location.
startDatestring(date-time)Start date of the cardholder.
endDatestring(date-time)End date of the cardholder.
statusstringStatus of the cardholder. One of: activated, blocked, expired, blacklisted, linked, or unlinked.
nameOnCardstringName that will be displayed on the cards for the cardholder.
notestringAdditional notes for the cardholder.
metadataobjectSet 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.
createdstring(date-time)Time at which the object was created.
cardslist, contains: card objectList 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

idstring(guid)Unique identifier for the object.
cardholderstring(guid)ID of the cardholder that the card belongs to.
cardNumberstringUnique, displayable identifier for the card.
chipserialNumberstringChip serial number of the card.
statusstringStatus of the card. One of: initialized, in_production, personalized, withdrawn, activated, blocked, expired, blacklisted, issued, returned, destroyed, bulk_blocked, linked, or unlinked.
typeobjectObject describing the card's type.
encryptionstringEncryption method used for the card. One of: aes, des, or triple_des.
layoutobjectObject describing the card's layout.
startDatestring(date-time)Start date of the card.
endDatestring(date-time)End date of the card.
pickupNoticebooleanCurrently not used.
metadataobjectSet 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.
createdstring(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

idstring(guid)Unique identifier for the object.
personNumberstringUnique, displayable identifier for the person.
profilestring(guid)ID of the person's profile.
addressPreferencestringPerson's preferred address type. One of: home, business, or po_box.
identificationTypestringPerson's preferred method of identification. One of: none, driver_license, passport, eu, or foreigner.
identificationTypeValuestringValue for the person's specified identification method.
firstNamestringFirst name of the person.
middleNamestringMiddle name of the person.
lastNamestringLast name of the person.
birthDatestring(date)Person's birthday, represented as an ISO 8601:2004 YYYY-MM-DD format.
genderstringPerson's gender. One of: not_specified, female, male, other, or decline.
prefixstringPerson's name prefix. One of: none, dr, mr, mrs, or ms.
suffixstringPerson's name suffix. One of: none, ii, iii, iv, jr, md, phd, or sr.
phoneNumberstringPerson'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.
mobileNumberstringPerson'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.
statusstringStatus of the person. One of: none, activated, blocked, expired, blacklisted, linked, or unlinked.
metadataobjectSet 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.
photostring(base-64)Person's photo.
createdstring(date-time)Time at which the object was created.
addresseslist, contains: address objectList of the person's addresses.
cardholderslist, contains: cardholder objectList 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

idstring(guid)Unique identifier for the object.
personstring(guid)ID of the person associated with the production.
cardholderstring(guid)ID of the cardholder associated with the production.
cardstring(guid)ID of the card associated with the production.
nameOnCardstringName that will be displayed on the card.
chipserialNumberstringChip serial number of the card.
userNamestringUser who initiated the card production process.
exportedbooleanIndicates whether the card has been exported.
printedOnstring(date-time)Date the card was printed.
numberOfTriesintegerNumber 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.

...