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:

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.

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

Endpoint: POST /api/v2/authenticate

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:

Sample Successful Response:

Fetch authenticated user profile

Endpoint: GET /api/v2/profile/me

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:

Error Status Codes

Sample Successful Response:

Create a Card

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

authorization

card[card_template_id]

card[data]

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:

Error Status Codes

Sample Successful Response:

Preview Card

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

authorization

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:

Error Status Codes

Sample Successful Response:

Update/Edit Card

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

authorization

card[data]

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:

Error Status Codes

Sample Successful Response:

Finalize Card

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

authorization

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:

Error Status Codes

Sample Successful Response:

Search for a Card

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

authorization

term

page_size

page

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:

Error Status Codes

Sample Successful Response:

Delete a Card

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

authorization

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:

Error Status Codes

Sample Successful Response:

Fetch All Cards

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

authorization

page_size

page

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:

Error Status Codes

Sample Successful Response:

Fetch a Single Card

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

authorization

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:

Error Status Codes

Sample Successful Response:

Card Print History

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

authorization

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:

Error Status Codes

Sample Successful Response:

Create a Print Job

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

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:

Error Status Codes

Sample Successful Response:

Update a Print Job

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

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:

Error Status Codes

Sample Successful Response:

Add Card(s) to a Print Job

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

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:

Error Status Codes

Sample Successful Response:

Remove a Card from a Print Job

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

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:

Error Status Codes

Sample Successful Response:

Check Balance to Submit a Print Job

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

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:

Error Status Codes

Sample Successful Response:

Submit a Print Job

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

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:

Error Status Codes

Sample Successful Response:

Print Job Charge Details

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

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

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch a Single Print Job

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

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:

Error Status Codes

Sample Successful Response:

Fetch All Print Jobs

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

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

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch Organization Details

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

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

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch Organization Balance

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

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:

Error Status Codes

Sample Successful Response:

Fetch Listt of Shipping Providers

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

This endpoint fetches all shipping providers available to your organization. The response is an array of JSON objects. Each object represents a shipping provider—giving both an ID number and the provider name. The ID number is what is used when creating a print job.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch a Single Print Job

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

This endpoint adds the specified “amount” to the organization’s account balance.If the payment is successfully processed, “true” will be returned. If not, you will receive an error message specific to the error (e.g. “error”: “Your card’s expiration year is invalid.”)

For testing purposes, you may use the following credit card details in the staging environment:

Sample Call:

Error Status Codes

Sample Successful Response:

Financial Transactions

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

This endpoint fetches every financial transaction for your organization. It returns an array of JSON objects. Each object contains all of the details for an individual transaction.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch Template IDs

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

This endpoint fetches all card templates for your organization by name and ID. It returns an array of JSON objects. Each object contains the template’s ID number and its name.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch a Template’s Fields

Endpoint: GET api/v2/organizations/{organization_id}/card_templates/{id}/fields

This endpoint fetches all of the variable fields for a given template. Each of these fields is a parameter when using the CREATE A CARD endpoint. Organizations with multiple templates will need to reference the fields for a given template when a new card is being created.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch All Addresses

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

This endpoint fetches all addresses.

Sample Call:

Error Status Codes

Sample Successful Response:

Create an Address

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

This endpoint creates a new shipping address. Since addresses were designed to work in tandem with your organization’s contacts, there is the option to associate the address with a contact or to create a contact within this endpoint (you must do one of these things).

(*) Important: You must either include contact name and email or include the ID of a pre-created contact. 

In this example we have created a contact within the create an address endpoint. If you wish to create a contact before defining his or her address, use the CREATE A CONTACT endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch a Single Address

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

This endpoint fetches a single address. If you do nt know the ID of the address you wish to find, use the FETCH ALL ADDRESSES endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Update an Address

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

This endpoint updates/changes an already existing shipping address.

Warning: If you failed to associate a contact with your address when creating it, this endpoint will return a 501 error.

In this example we change the address state to Colorado.

Sample Call:

Error Status Codes

Sample Successful Response:

Delete an Address

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

This endpoint deletes a single address. If you don’t know the ID of the address you wish to delete, use the FETCH ALL ADDRESSES endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch All Contacts

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

This endpoint fetches all contacts, along with the addresses associated with them. If you need to associate an address with a contact, use the UPDATE ADDRESS endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Create a Contact

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

This endpoint creates a new contact. Since contacts were designed to work in tandem with your organization’s addressess, there is the option to associate any address with a contact. You may do this by using the contact ID (once the contact is created) with the UPDATE ADDRESS endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch a Single Contact

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

This endpoint fetches a single contact. If you don’t know the ID of the contact you wish to find, use the FETCH ALL CONTACTS endpoint. If there are any addresses associated with the contact, they will be returned in an array with the “addresses” key.

Sample Call:

Error Status Codes

Sample Successful Response:

Update a Contact

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

This endpoint updates/edits an already existing contact. Since contacts were designed to work in tandem with your organization’s addresses, there is the option to associate any address with a contact. You may do this by using the contact ID (once the contact is created) with the UPDATE ADDRESS endpoint.

In this example, we update the given contact with an alt email and alt phone number.

Sample Call:

Error Status Codes

Sample Successful Response:

Delete a Contact

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

This endpoint deletes a single contact. If you don’t know the ID of the contact you wish to delete, use the FETCH ALL CONTACTS endpoint.

Sample Call:

Error Status Codes

Sample Successful Response: