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.
Test mode secret keys have the prefix sk_test_ and live mode secret keys have the prefix sk_live_.
Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.
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.
Attributes
| 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.
Action URL
POST /api/v1/addresses
Arguments
| person | required | The identifier of the person to add the address to. |
| type | required | The address' type. One of: home, business, or po_box. |
| streetAddress | required | Full street address component, which may include house number, street name, Post Office Box, and multi-line extended street address information. |
| locality | required | City or locality component. |
| region | required | State, province, prefecture, or region component. |
| postalCode | required | Zip code or postal code component. |
| country | required | Country name component. |
| metadata | optional | A set of key-value pairs that you can attach to an address object. It can be useful for storing additional information about the address in a structured format. |
Returns
Returns an address object if the call succeeded.
Retrieve an address
Retrieves the details of an existing address.
Action URL
GET /api/v1/addresses/:id
Arguments
| id (path) | required | The identifier of the address to be retrieved. |
Returns
Returns an address object if a valid identifier was provided.
Update an address
Updates the specified address.
Action URL
POST /api/v1/addresses/:id
Arguments
| id (path) | required | The identifier of the address to update. |
| person | optional | The identifier of the new person for this address. |
| type | optional | The address' type. One of: home, business, or po_box. |
| streetAddress | optional | Full street address component, which may include house number, street name, Post Office Box, and multi-line extended street address information. |
| locality | optional | City or locality component. |
| region | optional | State, province, prefecture, or region component. |
| postalCode | optional | Zip code or postal code component. |
| country | optional | Country name component. |
| metadata | optional | A set of key-value pairs that you can attach to an address object. It can be useful for storing additional information about the address in a structured format. |
Returns
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.
Action URL
DELETE /api/v1/addresses/:id
Arguments
| id (path) | required | The identifier of the address to be deleted. |
Returns
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.
Action URL
GET /api/v1/addresses
Arguments
q (query) | optional | Only return addresses that mention the given search term. |
person (query) | optional | The ID of the person whose addresses will be retrieved. |
| type (query) | optional | Only return addresses of the given type. One of: home, business, or po_box. |
| page (query) | optional | A cursor for use in pagination that defines your place in the list based on the number of objects to be returned. The default is 1. |
| per_page (query) | optional | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 15. |
Returns
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.
Action URL
POST /api/v1/anonymous-sets
Arguments
| profile | required | The identifier of the profile to use for the cardholders. |
| defaultName | required | The name of the set. |
| quantity | required | The number of cards to include in the set. |
| businessUnit | optional | The business unit to use for the cardholders. |
| externalCompany | optional | The external company to use for the cardholders. |
| department | optional | The department to use for the cardholders. |
| jobTitle | optional | The job title to use for the cardholders. |
| location | optional | The location to use for the cardholders. |
| costAccount | optional | The cost account to use for the cardholders. |
| note | optional | The note to use for the cardholders. |
Returns
Returns an anonymous set object if the call succeeded.
Retrieve an anonymous set
Retrieves the details of an existing anonymous set.
Action URL
GET /api/v1/anonymous-sets/:id
Arguments
| id (path) | required | The identifier of the anonymous set to be retrieved. |
Returns
Returns an anonymous set object if a valid identifier was provided.
Update an anonymous set
Adds additional cards to the specified anonymous set.
Action URL
POST /api/v1/anonymous-sets/:id
Arguments
| id (path) | required | The identifier of the anonymous set to update. |
| quantity | required | The number of cards to add to the set. |
| businessUnit | optional | The business unit to use for the cardholders. |
| externalCompany | optional | The external company to use for the cardholders. |
| department | optional | The department to use for the cardholders. |
| jobTitle | optional | The job title to use for the cardholders. |
| location | optional | The location to use for the cardholders. |
| costAccount | optional | The cost account to use for the cardholders. |
| note | optional | The note to use for the cardholders. |
Returns
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.
Action URL
GET /api/v1/anonymous-sets
Arguments
| q (query) | optional | Only return sets that mention the given search term. |
| profile (query) | optional | Only return sets for the given profile ID. |
| business_unit (query) | optional | Only return sets for the given business unit ID. |
| external_company (query) | optional | Only return sets for the given external company ID. |
| department (query) | optional | Only return sets for the given department ID. |
| location (query) | optional | Only return sets for the given location ID. |
| cost_account (query) | optional | Only return sets for the given cost account ID. |
| page (query) | optional | A cursor for use in pagination that defines your place in the list based on the number of objects to be returned. The default is 1. |
| per_page (query) | optional | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 15. |
Returns
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.
Action URL
POST /api/v1/cardholders
Arguments
| person | optional | The identifier of the person who the cardholder will belong to. |
| profile | required | The identifier of the profile for the cardholder. |
| loginId | optional | The username to use for the profile. |
| password | optional | The password to use for the profile. |
| optional | The email to use for the profile. | |
| businessUnit | optional | The identifier of the business unit to associate with the cardholder. |
| externalCompany | optional | The identifier of the external company to associate with the cardholder. |
| department | optional | The identifier of the department to associate with the cardholder. |
| startDate | optional | The date that the cardholder should become active from. |
| endDate | optional | The date that the cardholder should remain active until. |
| status | optional | The status of the cardholder. One of: activated, blocked, expired, blacklisted, linked, or unlinked. |
| location | optional | The identifier of the location to associate with the cardholder. |
| costAccount | optional | The identifier of the cost account to associate with the cardholder. |
| nameOnCard | optional | The name to display on the cards for the cardholder. |
| note | optional | Additional notes for the cardholder. |
| metadata | optional | A set of key-value pairs that you can attach to a cardholder object. It can be useful for storing additional information about the cardholder in a structured format. |
Returns
Returns a cardholder object if the call succeeded.
Retrieve a cardholder
Retrieves the details of an existing cardholder.
Action URL
GET /api/v1/cardholders/:id
Arguments
| id (path) | required | The identifier of the cardholder to be retrieved. |
Returns
Returns a cardholder object if a valid identifier was provided.
Update a cardholder
Updates the specified cardholder.
Action URL
POST /api/v1/cardholders/:id
Arguments
| id (path) | required | The identifier of the cardholder to update. |
| person | optional | The identifier of the new person who this cardholder will belong to. |
| profile | required | The identifier of the new profile for this cardholder. |
| loginId | optional | The username to use for the profile. |
| optional | The email to use for the profile. | |
| businessUnit | optional | The identifier of the business unit to associate with the cardholder. |
| externalCompany | optional | The identifier of the external company to associate with the cardholder. |
| department | optional | The identifier of the department to associate with the cardholder. |
| startDate | optional | The date that the cardholder should become active from. |
| endDate | optional | The date that the cardholder should remain active until. |
| status | optional | The status of the cardholder. One of: activated, blocked, expired, blacklisted, linked, or unlinked. |
| location | optional | The identifier of the location to associate with the cardholder. |
| costAccount | optional | The identifier of the cost account to associate with the cardholder. |
| nameOnCard | optional | The name to display on the cards for the cardholder. |
| note | optional | Additional notes for the cardholder. |
| metadata | optional | A set of key-value pairs that you can attach to a cardholder object. It can be useful for storing additional information about the cardholder in a structured format. |
Returns
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.
Action URL
DELETE /api/v1/cardholders/:id
Arguments
| id (path) | required | The identifier of the cardholder to be deleted. |
Returns
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.
Action URL
GET /api/v1/cardholders
Arguments
| q (query) | optional | Only return cardholders that mention the given search term. |
| person (query) | optional | The ID of the person whose cardholders will be retrieved. |
| profile (query) | optional | Only return cardholders for the given profile ID. |
| business_unit (query) | optional | Only return cardholders for the given business unit ID. |
| external_company (query) | optional | Only return cardholders for the given external company ID. |
| department (query) | optional | Only return cardholders for the given department ID. |
| location (query) | optional | Only return cardholders for the given location ID. |
| cost_account (query) | optional | Only return cardholders for the given cost account ID. |
| status (query) | optional | Only return cardholders with the given status. One of: activated, blocked, expired, blacklisted, linked, or unlinked. |
| starting_after (query) | optional | Only return cardholders that start after the given date. |
| ending_before (query) | optional | Only return cardholders that end before the given date. |
| page (query) | optional | A cursor for use in pagination that defines your place in the list based on the number of objects to be returned. The default is 1. |
| per_page (query) | optional | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 15. |
Returns
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.
Action URL
POST /api/v1/cards
Arguments
| cardholder | required | The identifier of the cardholder to add the card to. |
| metadata | optional | A set of key-value pairs that you can attach to a card object. It can be useful for storing additional information about the card in a structured format. |
Returns
Returns a card object if the call succeeded.
Retrieve a card
Retrieves the details of an existing card.
Action URL
GET /api/v1/cards/:id
Arguments
| id (path) | required | The identifier of the card to be retrieved. |
Returns
Returns a card object if a valid identifier was provided.
Update a card
Updates the specified card.
Action URL
POST /api/v1/cards/:id
Arguments
| id (path) | required | The identifier of the card to update. |
| status | optional | The new status of the card. One of: initialized, in_production, personalized, withdrawn, activated, blocked, expired, blacklisted, issued, returned, destroyed, bulk_blocked, linked, or unlinked. |
| metadata | optional | A set of key-value pairs that you can attach to a card object. It can be useful for storing additional information about the card in a structured format. |
Returns
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
GET /api/v1/cards
Arguments
| q (query) | optional | Only return cards that mention the given search term. |
| cardholder (query) | optional | The ID of the cardholder whose cards will be retrieved. |
| status (query) | optional | Only return cards with the given status. One of: initialized, in_production, personalized, withdrawn, activated, blocked, expired, blacklisted, issued, returned, destroyed, bulk_blocked, linked, or unlinked. |
| type (query) | optional | Only return cards of the given type. |
| encryption (query) | optional | Only return cards using the given encryption method. One of: aes, des, or triple_des. |
| layout (query) | optional | Only return cards with the given layout. |
| starting_after (query) | optional | Only return cards that start after the given date. |
| ending_before (query) | optional | Only return cards that end before the given date. |
| page (query) | optional | A cursor for use in pagination that defines your place in the list based on the number of objects to be returned. The default is 1. |
| per_page (query) | optional | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 15. |
Returns
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.
Action URL
POST /api/v1/persons
Arguments
| profile | optional | The identifier of the profile for the person. |
| addressPreference | optional | The person's preferred address type. One of: home, business, or po_box. |
| identificationType | optional | The person's preferred method of identification. One of: none, driver_license, passport, eu, or foreigner. |
| identificationTypeValue | optional | The value for the person's specified identification method. |
| firstName | required | The person's first name. |
| middleName | optional | The person's middle name. |
| lastName | required | The person's last name. |
| birthDate | required | The person's birthday, represented as an ISO 8601:2004 YYYY-MM-DD format. |
| gender | optional | The person's gender. One of: not_specified, female, male, other, or decline. |
| prefix | optional | The person's name prefix. One of: none, dr, mr, mrs, or ms. |
| suffix | optional | The person's name suffix. One of: none, ii, iii, iv, jr, md, phd, or sr. |
| phoneNumber | optional | The 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 | optional | The 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 | optional | The person's status. One of: none, activated, blocked, expired, blacklisted, linked, or unlinked. |
| metadata | optional | A set of key-value pairs that you can attach to a person object. It can be useful for storing additional information about the person in a structured format. |
| photo | optional | The person's photo. |
Returns
Returns a person object if the call succeeded.
Retrieve a person
Retrieves the details of an existing person.
Action URL
GET /api/v1/persons/:id
Arguments
| id (path) | required | The identifier of the person to be retrieved. |
Returns
Returns a person object if a valid identifier was provided.
Update a person
Updates the specified person.
Action URL
POST /api/v1/persons/:id
Arguments
| id (path) | required | The identifier of the person to update. |
| profile | optional | The identifier of the new profile for this person. |
| addressPreference | optional | The person's preferred address type. One of: home, business, or po_box. |
| identificationType | optional | The person's preferred method of identification. One of: none, driver_license, passport, eu, or foreigner. |
| identificationTypeValue | optional | The value for the person's specified identification method. |
| firstName | required | The person's first name. |
| middleName | optional | The person's middle name. |
| lastName | required | The person's last name. |
| birthDate | required | The person's birthday, represented as an ISO 8601:2004 YYYY-MM-DD format. |
| gender | optional | The person's gender. One of: not_specified, female, male, other, or decline. |
| prefix | optional | The person's name prefix. One of: none, dr, mr, mrs, or ms. |
| suffix | optional | The person's name suffix. One of: none, ii, iii, iv, jr, md, phd, or sr. |
| phoneNumber | optional | The 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 | optional | The 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 | optional | The person's status. One of: none, activated, blocked, expired, blacklisted, linked, or unlinked. |
| metadata | optional | A set of key-value pairs that you can attach to a person object. It can be useful for storing additional information about the person in a structured format. |
| photo | optional | The person's photo. |
Returns
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.
Action URL
DELETE /api/v1/persons/:id
Arguments
| id (path) | required | The identifier of the person to be deleted. |
Returns
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.
Action URL
GET /api/v1/persons
Arguments
| q (query) | optional | Only return persons that mention the given search term. |
| address_preference (query) | optional | Only return persons who have the given address preference. One of: home, business, or po_box. |
| id_type (query) | optional | Only return persons who use the given method of identification. One of: none, driver_license, passport, eu, or foreigner. |
| gender (query) | optional | Only return persons of the given gender. One of: not_specified, female, male, other, or decline. |
| prefix (query) | optional | Only return persons with the given name prefix. One of: none, dr, mr, mrs, or ms. |
| suffix (query) | optional | Only return persons with the given name suffix. One of: none, ii, iii, iv, jr, md, phd, or sr. |
| production_status (query) | optional | Only return persons who have a card in the given production stage. One of: to_be_created, to_be_produced, produced, or to_be_activated. |
| page (query) | optional | A cursor for use in pagination that defines your place in the list based on the number of objects to be returned. The default is 1. |
| per_page (query) | optional | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 15. |
Returns
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.
Action URL
GET /api/v1/productions/:id
Arguments
| id (path) | required | The identifier of the production record to be retrieved. |
Returns
Returns a production object if a valid identifier was provided.
Update a production
Updates the specified production record.
Action URL
POST /api/v1/productions/:id
Arguments
| id (path) | required | The identifier of the production record to update. |
| nameOnCard | optional | The name to display on the card. |
| chipserialNumber | optional | The chip serial number of the card. |
| userName | optional | The user associated with the production. |
| printedOn | optional | The date the card was printed. |
| numberOfTries | optional | The number of tries needed to successfully print the card. |
Returns
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.
Action URL
GET /api/v1/productions
Arguments
| q (query) | optional | Only return production records that mention the given search term. |
Returns
A list of up to per_page records, starting at page. Passing the optional search query will result in filtering to only records that mention the supplied value. Passing any of the optional filters will result in filtering to records with only those exact values. Each entry in the list is a separate production object. If no more records 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.