Introduction

The InstantCard JSON/REST API .  All API responses are JSON  (including errors), but are easily converted to objects in any language. We use standard HTTP status/response codes.

To facilitate testing, all examples use a dummy account in a staging environment https://staging.core.instantcard.net/api/v2/. To implement our APIs in a production environment, you must use the base path

https://core.instantcard.net/api/v2/

In lieu of a standard API key, we use a login/authentication POST method to retrieve a login token. This token is then used for all subsequent calls. Since this token has an expiry, authentication is required for each session.

Note on contacts and addresses:
While separated into different sections, with their own endpoints, contacts and addresses were designed to work in tandem. To this end, individual contacts may be linked to individual addresses and vise-versa. If you wish to treat these as a single entity, you may define all fields through the ADDRESSES endpoints (which accepts all parameters that define a contact).

It is possible that you wish to see an example call implemented in a language which we haven’t shown. In this case, please feel free to contact us and we’ll add it as soon as possible.

To test the API for yourself without an account, feel free to use the following credentials:

Base URL https://staging.core.instantcard.net/api/v2/
Email [email protected]
Password instantcardapi
Organization ID 20003827

The InstantCard API was designed with  certain workflows in mind. For example, in creating a card we developed a system designed to create a draft, preview that draft, and update if needed before any sort of finalization. So, to this end feel free to consult some of the following recommended workflows. You will notice that many of our endpoints do not make it into these examples, as they aren’t required by the typical client.

If there is any workflow you would like to see, but isn’t listed here, please feel free to Contact Us.

Workflow

Authentication Flow

Your authentication token is a required parameter for all subsequent calls.

  1. Login
    • Use the AUTHENTICATE USER → endpoint to fetch your authetication token.
  2. User Profile
    • Use the FETCH USER PROFILE → endpoint to then get the information of the user.

Create a New Card

The API was designed to create a card as draft, preview the draft, and if the preview looks good, you can either finalize or go back and update the card.

  1. Create Draft
    • Use the CREATE A NEW CARD → endpoint to create your draft. (Remember, this does not finalize the card, and it will not yet be available for printing.)
  2. Preview Card
    • Use the PREVIEW CARD → endpoint to then check the draft created (this is particularly useful when using a cropping tool and verifying the card image looks as desired).
  3. If there’s an issue, Update Card, and preview again.
    • Use the UPDATE CARD → endpoint to fix any errors found after previewing.
    • Make sure to PREVIEW CARD → once more to verify the new changes are correct.
  4. If it looks good, Finalize Card
    • If everything looks correct after your last preview, use the FINALIZE CARD → endpoint to finalize the new card. Once finalized, it may be added to a print job.

Checkout Process

Similarly to card creation, a print job must be finalized before its cards are sent to the printer. This allows print jobs to be modified before being finalized. It also facilitates having a “shopping cart” while a user continues to add cards.

  1. Create Print Job
    • Use the CREATE A PRINT JOB → endpoint to create your print job. Cards may be added during creation, later, or both.
  2. Add Cards to Print Job
    • Use the ADD CARDS TO A PRINT JOB → endpoint to add more cards to the print job you already created.
  3. Select how many copies of each card
    • Use the UPDATE PRINT JOB → endpoint to select how many copies you would like of each card in the print job.
    Note: Every card in a given print job will have the same number of copies applied to it. If you need a different amount of a given card, create a separate print job for that card.
  4. Select your shipping provider
    • Use the FETCH SHIPPING PROVIDERS → endpoint to list all available shipping providers.
    UPDATE PRINT JOB → with your desired shipping provider ID.
  5. Select a Delivery Address
    • Use the FETCH ALL ADDRESSES → endpoint to retrieve all available shipping addresses.
    • Create a new shipping address if the required address is not listed using the CREATE SHIPPING ADDRESS → endpoint.
    • If you need to use a one-time address (i.e. you do not want it save for future use) you may use the UPDATE PRINT JOB → endpoint to add one-off shipping address details to the print job.
  6. Check Account Balance
    • Use the CHECK BALANCE → endpoint to make sure there are enough funds to cover the print job before submitting.
    • If the account needs replenishing, use the ADD FUNDS → endpoint.
  7. Submit Job for Print Production
    • Use the SUBMIT PRINT JOB → endpoint to submit the print job for print production.
    Note: Orders placed before 4PM EST are printed and shipped same day, so it is important to verify that a print jobs details are correct before submitting.

Login / Authenticate User

Login

Endpoint: POST /api/v2/authenticate

key description
email
(required) the email used to access your account at https://online.instantcard.net
password
(required) the password used to access your account at https://online.instantcard,net

Before performing any other API calls you must first login, or authenticate, the user. To do so, submit your e-mail and password. These are the same e-mail and password which you use to access the regular InstantCard system (https://online.instantcard.net). If the e-mail/password combination is correct a token will be sent. If the e-mail/password combination is incorrect, a 401 response message will be returned.

This token is a required parameter for all subsequent API calls.

This token has an expiry. Therefore, you need to login before each session to ensure you are using a valid token for subsequent calls.

For testing purposes you may use the following credentials (only email and password are required for this endpoint):

email: [email protected]
password: instantcardapi
organization ID: 20003827 (InstantCard API)

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Sample Successful Response:

Copy to Clipboard

Fetch authenticated user profile

Endpoint: GET /api/v2/profile/me

key description
authorization
(required | include in header) “bearer” followed by a space and the token returned for authentication

Once you have successfully logged in, you may retrieve your stored user information via this endpoint. This may be used to display the logged-in username, etc.

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
400 Bad Request

Sample Successful Response:

Copy to Clipboard

Cards (Creation/Management)

Create a Card

Endpoint: POST api/v2/organizations/{organization_id}/cards

key description
authorization
(required | include in header) “bearer” followed by a space and the token returned for authentication
card[card_template_id]
(required | include as form-data in request body) the ID for the card template you wish to use
card[data]
(required | include as form-data in request body) a JSON array of objects representing each variable field in your card template. Photos need to be sent as Base64 (not through the image upload endpoint).

First you must create the new card based on and existing template. If you do not know the ID for your template, you may retrieve a list of templates using the CARD TEMPLATES ENDPOINT. Additionally, each template will have different variable fields needed for the “data” key value. If you do not know these values, you may retrieve them using the TEMPLATE FIELDS ENDPOINT.

For brevity, there is an “*” placed where normally there would be a Base64 string.  Here’s a helpful reference on using JavaScript to decode an image to Base64 →

NOTE: The card created via this endpoint will not be ready for printing. It must first be finalized using the FINALIZE CARD endpoint. This way you may PREVIEW CARD and UPDATE CARD if necessary before finalization.

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
400 Bad Request
500 Requested Range Not Satisfyable

Sample Successful Response:

Copy to Clipboard

Preview Card

Endpoint: GET api/v2/organizations/{organization_id}/cards/{id}/preview

key description
authorization
(required | include in header) “bearer” followed by a space and the token returned for authentication

This is used to preview the card you just created (or may be used after the card is finalized). While the card ID is not added as a header key/value, it is required within the endpoint URL. This Card ID number is the same as that returned in the first entry in the JSON object returned when using the CREATE A CARD endpoint.

Note: If you don’t know the card ID for the card you wish to preview, please use the SEARCH FOR A CARD endpoint.

This endpoint returns two Base64  strings representing both the front and the back card images. For brevity, there is an “*” placed where normally there would be a Base64 string.  Here’s a helpful reference on using JavaScript to decode a Base64 string→

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized

Sample Successful Response:

Copy to Clipboard

Update/Edit Card

Endpoint: PATCH api/v2/organizations/{organization_id}/cards/{id}

key description
authorization
(required | include in header) “bearer” followed by a space and the token returned for authentication
card[data]
(required | include as form-data in request body) a JSON array of objects representing each updated variable field in your card template. Photos need to be sent as Base64 (not through the image upload endpoint).

If there is a problem with the card you just created, you may use this endpoint to make changes before finalization. This may also be used to update finalized card items—for example, if you wish to update the expiry for a given card.

While the card ID is not added as a header key/value, it is required within the endpoint URL. This Card ID number is the same as that returned in the first entry in the JSON object returned when using the CREATE A CARD endpoint.

Note: If you don’t know the card ID for the card you wish to preview, please use the SEARCH FOR A CARD endpoint.

For brevity, there is an “*” placed where normally there would be a Base64 string.  Here’s a helpful reference on using JavaScript to decode an image to Base64 →

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
400 Bad Request
401 Unauthorized
404 Not Found

Sample Successful Response:

Copy to Clipboard

Finalize Card

Endpoint: PATCH api/v2/organizations/{organization_id}/cards/{id}/finalize

key description
authorization
(required | include in header) “bearer” followed by a space and the token returned for authentication

This is used to finalize a card. All cards must be finalized before they may be added to a print job. While the card ID is not added as a header key/value, it is required within the endpoint URL. This Card ID number is the same as that returned in the first entry in the JSON object returned when using the CREATE A CARD endpoint.

Note: If you don’t know the card ID for the card you wish to preview, please use the SEARCH FOR A CARD endpoint.

This endpoint may return Base64 strings where there are images found on the card. For brevity, there is an “*” placed where normally there would be a Base64 string.  Here’s a helpful reference on using JavaScript to decode a Base64 string→

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
400 Bad Request
401 Unauthorized
404 Not Found

Sample Successful Response:

Copy to Clipboard

Search for a Card

Endpoint: GET /api/v2/organizations/20003827/cards/search

key description
authorization
(required | include in header) “bearer” followed by a space and the token returned for authentication
term
(required) the search terms as one string
page_size
the number of cards to return for a given page
page
which page to return

This endpoint uses a string to search for a card or cards. It returns a JSON array of objects. Each object contains a card’s ID, template ID, organization ID, its data, and when it was last printed/submitted for printing.

All images return the value “image” to reduce the information returned. To preview images, please use the PREVIEW CARD endpoint.

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
400 Bad Request
404 Not Found

Sample Successful Response:

Copy to Clipboard

Delete a Card

Endpoint: DELETE api/v2/organizations/{organization_id}/cards/{id}

key description
authorization
(required | include in header) “bearer” followed by a space and the token returned for authentication

This endpoint deletes a given card.

If you do not know the ID of the card you wish to delete, use the SEARCH for a CARD endpoint.

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
404 Not Found

Sample Successful Response:

Copy to Clipboard

Fetch All Cards

Endpoint: GET api/v2/organizations/{organization_id}/cards

key description
authorization
(required | include in header) “bearer” followed by a space and the token returned for authentication
page_size
the number of cards to return for each page
page
which page to return

This endpoint retrieves every card for a given organization. It returns a JSON array of objects. Each object contains a card’s ID, template ID, organization ID, its data, and when it was last printed/submitted for printing.

All images return the value “image” to reduce the information returned. To preview images, please use the PREVIEW CARD endpoint.

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized

Sample Successful Response:

Copy to Clipboard

Fetch a Single Card

Endpoint: GET api/v2/organizations/{organization_id}/cards/{id}

key description
authorization
(required | include in header) “bearer” followed by a space and the token returned for authentication

This enpoint returns a JSON object which contains a card’s ID, template ID, organization ID, its data, and when it was last printed/submitted for printing.

If you do not know the ID of the card you wish to fetch, use the SEARCH for a CARD endpoint.

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
404 Not Found

Sample Successful Response:

Copy to Clipboard

Card Print History

Endpoint: GET api/v2/organizations/{organization_id}/cards/{id}/print_history

key description
authorization
(required | include in header) “bearer” followed by a space and the token returned for authentication

This endpoint gives the print history of a given card. It returns a JSON array of objects. Each object represents one print order and includes both the status and the time it was processed. A status of “0” indicates the card has not yet been printed. A status of “1” indicates the card has been printed and sent.

If you do not know the ID of the card whose history you wish to view, use the SEARCH for a CARD endpoint.

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
404 Not Found

Sample Successful Response:

Copy to Clipboard

Print Jobs  (Ordering, Checkout)

Create a Print Job

Endpoint: POST api/v2/organizations/{organization_id}/print_jobs

Parameter Description Parameter Type Data Type
Authorization (Required) “bearer” followed by the authentication token returned at login path string
organization_id (Required) Organization ID path integer
print_job[address_id] Address Id body form-data integer
print_job[address][contact][full_name] One off Address Full name body form-data string
print_job[address][organization_name] One off Address Organization name body form-data string
print_job[address][address_1] One off Address 1 body form-data string
print_job[address][address_2] One off Address 2 body form-data string
print_job[address][city] One off Address City body form-data string
print_job[address][state] One off Address State body form-data string
print_job[address][zip_code] One off Address Zip code body form-data integer
print_job[address][country] One off Address Country body form-data string
print_job[shipping_provider_id] Shipping Provider Id body form-data integer
print_job[number_of_copies] Number of copies of each card to print body form-data integer
print_job[card_ids] IDs of cards to add to print job body form-data array

To order cards, you must create a new print job. You may either elect to use an address on file or a “One off” address. One-off address data is not saved and is used only for the given print job. To send to a new address you want saved or to search for an adress ID which already exists, use the ADDRESSES endpoints.

Once created, a print job may be modified via the UPDATE PRINT JOB endpoint, or you may add cards to it via the ADD CARDS endpoint. (This is why the “print_job[card_ids]” parameter is not required when initially creating a print job.) If you do not know the ID of your desired shipping provider, you may retrieve a list of available shipping providers using the SHIPPING PROVIDERS endpoint.

NOTEs:
• Creating a print job will not automatically send cards to be printed. You must use the SUBMIT PRINT JOB endpoint to finalize an order.
• The print_job[card_ids] parameter should be an array of strings—each string being a card ID number. Even if you are ordering a single card, it must be in the form “[264561]

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
400 Bad Request

Sample Successful Response:

Copy to Clipboard

Update a Print Job

Endpoint: PATCH api/v2/organizations/{organization_id}/print_jobs/{id}

Parameter Description Parameter Type Data Type
Authorization (Required) “bearer” followed by the authentication token returned at login header string
organization_id (Required) Organization ID path integer
organization_id (Required) Print Job ID path integer
print_job[address_id] Address Id URL parameter integer
print_job[address][contact][full_name] One off Address Full name URL parameter string
print_job[address][organization_name] One off Address Organization name URL parameter string
print_job[address][address_1] One off Address 1 URL parameter string
print_job[address][address_2] One off Address 2 URL parameter string
print_job[address][city] One off Address City URL parameter string
print_job[address][state] One off Address State URL parameter string
print_job[address][zip_code] One off Address Zip code URL parameter integer
print_job[address][country] One off Address Country URL parameter string
print_job[shipping_provider_id] Shipping Provider Id URL parameter integer
print_job[number_of_copies] Number of copies of each card to print URL parameter integer
print_job[card_ids] IDs of cards to add to print job URL parameter array

To update a print job which was already created, use this endpoint.

Note: patching the print job automatically resets the shipping provider id to “null.” Make sure to resend this value with the patch.

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
400 Bad Request
404 Not Found

Sample Successful Response:

Copy to Clipboard

Add Card(s) to a Print Job

Endpoint: POST api/v2/organizations/{organization_id}/print_jobs/{id}/add_cards

Parameter Description Parameter Type Data Type
Authorization (Required) “bearer” followed by the authentication token returned at login header string
organization_id (required) Organization ID path string
id (required) Print Job Id path integer
print_job[card_ids] IDs of cards to be added to the print job body form-data array

Use this endpoint to add cards to a print job which already exists. If you do not know the print job ID, use the FETCH ALL PRINT JOBS endpoint.

Note: The number of each card printed is inherent to the print job itself. By adding a card to a given job, you will be requesting whatever number of cards is specified within that job. If you need a different amount of a given card, create a new print job.

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
400 Bad Request
404 Not Found

Sample Successful Response:

Copy to Clipboard

Remove a Card from a Print Job

Endpoint: DELETE api/v2/organizations/{organization_id}/print_jobs/{id}/remove_cards/{card_id}

Parameter Description Parameter Type Data Type
Authorization (Required) “bearer” followed by the authentication token returned at login header string
organization_id Organization ID path integer
id Print Job ID path integer
card_id Card ID path integer

This endpoint will remove an individual card from a print job. To remove multiple cards you must call this endpoint for each card.

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
404 Not Found
500 Internal Server Error

Sample Successful Response:

Copy to Clipboard

Check Balance to Submit a Print Job

Endpoint: GET api/v2/organizations/{organization_id}/print_jobs/{id}/check_balance

Parameter Description Parameter Type Data Type
Authorization (Required) “bearer” followed by the authentication token returned at login header string
organization_id (Required) Organization ID path integer
id (Required) Print Job Id path integer

Before submitting a print job, you must check the account balance to make sure there are enough funds to cover the given job.

If the balance covers the print job, “true” is returned; if not, “false” is returned.

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard
$request->setMethod(HTTP_METH_GET);

$request->setHeaders(array(
‘Cache-Control’ => ‘no-cache’,
‘Authorization’ => ‘bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxMzQyMCwiZXhwIjoxNTMxMzYxNTA5fQ.nVuv54VZfRHAeqFZYyHO4hYLF_GPVV1yL7iPT4T6xyk’
));

try {
$response = $request->send();

echo $response->getBody();
} catch (HttpException $ex) {
echo $ex;
}[/fu_syntax_highlighter]

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
400 Bad Request
404 Not Found

Sample Successful Response:

Copy to Clipboard

Submit a Print Job

Endpoint: POST api/v2/organizations/{organization_id}/print_jobs/{id}/print

Parameter Description Parameter Type Data Type
Authorization (Required) “bearer” followed by the authentication token returned at login header string
organization_id (Required) Organization ID path integer
id (Required) Print Job Id path integer

Once you are ready to send a print job to be printed, and have verified there are enough funds for the given job, you may use this endpoint to submit a print job.

Note: Print Jobs submitted before 4PM EST are printed and shipped same day. Please make sure to verify all details for a given print job before submitting, as it is likely to be fulfilled right away.

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
400 Bad Request
404 Not Found

Sample Successful Response:

Copy to Clipboard

Print Job Charge Details

Endpoint: GET api/v2/organizations/{organization_id}/print_jobs/{id}/charge_details

Parameter Description Parameter Type Data Type
Authorization (Required) “bearer” followed by the authentication token returned at login header string
organization_id (Required) Organization ID path integer
id (Required) Print Job Id path integer

Use this endpoint to fetch charge detail for an already submitted print job.

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
400 Bad Request
404 Not Found

Sample Successful Response:

Copy to Clipboard

Fetch a Single Print Job

Endpoint: GET api/v2/organizations/{organization_id}/print_jobs/{id}

Parameter Description Parameter Type Data Type
Authorization (Required) “bearer” followed by the authentication token returned at login header string
organization_id (Required) Organization ID path integer
id (Required) Print Job Id path integer

This endpoint fetches a single print job. You may use thi to check whether a print job is correct before using the SUBMIT PRINT JOB endpoint, or to verify that a given job has been submitted.

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
404 Not Found

Sample Successful Response:

Copy to Clipboard

Fetch All Print Jobs

Endpoint: GET api/v2/organizations/{organization_id}/print_jobs

Page numberqueryinteger

Parameter Description Parameter Type Data Type
Authorization (Required) “bearer” followed by the authentication token returned at login header string
organization_id (Required) Organization ID path integer
page which page to return URL parameter
integer
page_size how many print jobs to return per page URL parameter integer
status job status—fetch either submitted or non-submitted print jobs (Created: 0, Submitted: 1) URL parameter integer

This endpoint fetches all print jobs. You may also specify between created (not submitted) and submitted print jobs using the optional “status” parameter.

Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Sample Call:


Error Status Codes

HTTP Status Code Reason
401 Unauthorized
404 Not Found

Sample Successful Response:

Copy to Clipboard

Organization (Funds, Settings)

Fetch Organization Details

Endpoint: GET api/v2/organizations/{id}

Parameter Description Parameter Type Data Type
Authorization (Required) “bearer” followed by the authentication token returned at login header string
organization_id (Required) Organization ID path integer

This endpoint fetches your organization’s name, total number of cards, and number of card templates.

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
404 Not Found

Sample Successful Response:

Copy to Clipboard

Fetch Organization Balance

Endpoint: GET api/v2/organizations/{id}/balance

Parameter Description Parameter Type Data Type
Authorization (Required) “bearer” followed by the authentication token returned at login header string
organization_id (Required) Organization ID path integer

This endpoint fetches your organization’s current balance. If the balance is negative (i.e. in overdraft) it is returned in parenthesis.

$5.50—Positive Balance
($5.50)—Negative Balance

If you need to add more funds to your account, please use the ADD FUNDS endpoint.

Sample Call:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
404 Not Found

Sample Successful Response:

Copy to Clipboard

Fetch Listt of Shipping Providers

Endpoint: GET api/v2/organizations/{id}/shipping_providers