>API
API2018-09-19T10:25:12+00:00

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: instantcardapitest
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

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

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:


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 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
amount (Required) Amount to add (in the form 17.37 or 17,000.37) body form-data float
number (Required) credit card number (with no spaces nor dashes)
body form-data integer
exp_month (Required) in the form “MM” body form-data integer
exp_year (Required) in the form “YYYY” body form-data integer
cvc (Required) the three-digit security code on the back of the card body form-data integer
full_name (Required) the full name of the card holder body form-data string
billing_address1 (Required) billing address 1 body form-data string
billing_address2 billing address 2 body form-data string
billing_country (Required) billing country body form-data string
billing_city (Required) billing city body form-data string
billing_state (Required) billing state code (e.g. PA) body form-data string
billing_zip_code (Required) billing zip code body form-data integer

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:

number 4242424242424242
expiration month
06
expiration year
2029
cvc 424
full name
InstantCard API
billing address 1
418 Highland Rd.
billing country
USA
billing city
Feasterville
billing state
PA
billing zip code
19053

Sample Call:


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

Financial Transactions

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

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

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:


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 Templates

Fetch Template IDs

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

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 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:


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 Template’s Fields

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

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)Template ID path integer

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:


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

Addresses

Fetch All Addresses

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

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

This endpoint fetches all addresses.

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

Create an Address

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

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
address[organization_name] The name of the org. this address belongs to body form-data string
address[contact_id] (*) If you wish to associate address to a predefined contact, include ID body form-data string
address[contact][full_name] (*) Contact Full name (to create contact with address) body form-data string
address[contact][email] (*) Contact Email (to create contact with address) body form-data string
address[contact][alt_email] Contact Alt email (to create contact with address) body form-data string
address[contact][phone_number] Contact Phone number (to create contact with address) body form-data string
address[contact][alt_phone_number] Contact Alt phone number (to create contact with address) body form-data string
address[label] Address label body form-data string
address[primary] true” if primary address. If not, submit “false” or do not include parameter. body form-data string
address[address1] (Required) Address1 body form-data string
address[address2] Address2 body form-data string
address[city] (Required) City body form-data string
address[state] (Required) State body form-data string
address[zip_code] (Required) Zip code body form-data integer
address[country] (Required) Country Code body form-data string

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:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
406 Not Acceptable

Sample Successful Response:

Copy to Clipboard

Fetch a Single Address

Endpoint: GET api/v2/organizations/{organization_id}/addresses/{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) Address ID path
integer

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:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
404 Not Found
406 Not Acceptable

Sample Successful Response:

Copy to Clipboard

Update an Address

Endpoint: PATCH api/v2/organizations/{organization_id}/addresses/{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) Address ID path integer
address[organization_name] The name of the org. this address belongs to URL parameter string
address[contact_id] If you wish to associate address to a contact, include ID URL parameter string
address[contact][full_name] Contact Full name (to create contact with address) URL parameter string
address[contact][email] Contact Email (to create contact with address) URL parameter string
address[contact][alt_email] Contact Alt email (to create contact with address) URL parameter string
address[contact][phone_number] Contact Phone number (to create contact with address) URL parameter string
address[contact][alt_phone_number] Contact Alt phone number (to create contact with address) URL parameter string
address[label] Address label URL parameter string
address[primary] true” if primary address. If not, submit “false” or do not include parameter. URL parameter string
address[address1] Address 1 URL parameter string
address[address2] Address 2 URL parameter string
address[city] City URL parameter string
address[state] State URL parameter string
address[zip_code] Zip code URL parameter integer
address[country] Country Code URL parameter string

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:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
406 Not Acceptable

Sample Successful Response:

Copy to Clipboard

Delete an Address

Endpoint: DELETE api/v2/organizations/{organization_id}/addresses/{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) Address ID path
integer

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:


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

Contacts

Fetch All Contacts

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

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

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:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
406 Not Acceptable

Sample Successful Response:

Copy to Clipboard

Create a Contact

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

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
contact[full_name] (Required) Contact Full name body form-data string
contact[email] (Required) Contact Email body form-data string
contact[alt_email] Contact Alt email body form-data string
contact[phone_number] Contact Phone number body form-data string
contact[alt_phone_number] Contact Alt phone number body form-data string

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:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
406 Not Acceptable

Sample Successful Response:

Copy to Clipboard

Fetch a Single Contact

Endpoint: GET api/v2/organizations/{organization_id}/contacts/{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) Contact ID path
integer

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:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
404 Not Found
406 Not Acceptable

Sample Successful Response:

Copy to Clipboard

Update a Contact

Endpoint: PATCH api/v2/organizations/{organization_id}/contacts/{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) Contact ID path integer
contact[full_name] Contact Full name URL parameter string
contact[email] Contact Email URL parameter string
contact[alt_email] Contact Alt email URL parameter string
contact[phone_number] Contact Phone number URL parameter string
contact[alt_phone_number] Contact Alt phone number URL parameter string

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:


Copy to Clipboard
Copy to Clipboard
Copy to Clipboard

Error Status Codes

HTTP Status Code Reason
401 Unauthorized
406 Not Acceptable

Sample Successful Response:

Copy to Clipboard

Delete a Contact

Endpoint: DELETE api/v2/organizations/{organization_id}/contacts/{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) Contact ID path
integer

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:


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

Coming Soon