API Documentation
We provide an API to allow businesses / organizations to create and manage cards programmatically. This API works in conjunction with our other organization tools, like our analytics and custom branding. See also our documentation for building group video themes. Please contact us with any questions.
Contents
Getting started
First, get your API access key from the API tab in the organization tools page. You must be an organization administrator to access this page, and your organization must be enrolled in plan that supports API access. The tools there also let you delete and generate new access keys.
The Ellacard API follows the op-dev pattern. You interact with the API using JSON remote procedure calls. There is a Python client available that makes it easier to interact with the API by automatically serializing / deserializing requests and managing re-authentication. See the curl example to better understand the raw mechanism / headers for making calls.
Please see below for a more comprehensive example of how to use the API.
pip install https://pypi.op-dev.io/op-service-client/op-service-client-0.1.0.tar.gz
#!/usr/bin/env python3
# Set this variable first
API_ACCESS_KEY = …
import json
from op_service_client import OPServiceClient
client = OPServiceClient(
url='https://api.ellacard.com',
auth={ 'route': 'auth', 'params': { 'key': API_ACCESS_KEY } }
)
# The 'OPServiceClient' will automatically authenticate (and re-authenticate) as needed
output = client.call('list-orders')
print(json.dumps(output, indent=2))
Overview
The Ellacard API lets you create, get, list, update, and cancel orders. All your orders will be tied to your organization (thus they'll automatically respect any custom branding you have enabled), and each order must be owned by an individual user in your organization. This allows you to use the Ellacard account tools to manually manage any individual order if necessary. Please contact us to create an Ellacard organization account, or to add API access to your existing organization account.
There are two primary ways users interact with Ellacard orders: via the order-sign and order-open views. Note that both of these views can be entirely embedded on your own website (see the "Embedding" tab in the organization tools). The order-sign view allows anyone to add content to the card without an account. Note the "allow_gift_cards" and "allow_replace_designs" flags in the create-order and update-order endpoints that give you some control over the features available in the order-sign interface. The owner of the order can also "lock" the order to prevent others from being able to add / edit content via the order-sign interface (this happens automatically when we deliver an order).
You can set your orders to auto-send or not by specifying a "send_at" time. In the former case, each recipient you specify will receive a unique link that leads to the order-open view, which allows us to track which recipients have actually opened the order. We also generate a separete unique link that also leads to the order-open view, which you can distribute yourself.
Note that you can update any of the order details at any time, unless the order has already been auto-sent.
We provide a dashboard that summarizes all your organization's orders. It is accessible only to organization administrators in the orders tab in the organization tools page. You can also retrieve a list of your organization's orders via the list-orders API (using the appropriate access key).
You can test your integration with the API using the sandbox access keys for free with all features available, but all associated orders will have a watermark. When placing an order in production, your organization's credits / discounts will be automatically applied.
User IDs
Each order you create must be owned by a user who is a member of your organization. To find a user's ID, open the "Users" tab in the organization tools and click the info icon in the corresponding row.
Design IDs
You can specify a design ID when creating an order. To find the ID for one of the designs in our card catalog, just select a design, then copy the URL suffix – https://ellacard.com/cards/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Note that you can also use your own custom designs, such as those created via the create reusable card tool – the resulting link has a similar suffix.
Endpoints
/auth
Uses your access key to get a temporary JWT that can be used to call other APIs. You can generate and delete access keys in the "API" tab in the organization tools.
Note that the output JWT will have the "exp" property set, so you can check if you need to re-authenticate before making a service call (the Python 3 client does this automatically). You can use this tool to see the information we encode in the JWT.
{
"key": non_empty_str
}
non_empty_str
/create-order
Creates an order with the specified details and returns the order ID in addition to the order-sign and order-open links, which will respect any custom branding your organization has set up.
{
"user_id": uuid_str,
"[design_id]": nullable(uuid_str),
"[from]": nullable(non_empty_str),
"[recipients]": nullable([
{
"to": nullable(non_empty_str),
"[email]": email_address,
"[text]": us_phone_number
},
…
]),
"[send_at]": nullable(iso_datetime_str),
"[allow_gift_cards]": bool,
"[allow_replace_design]": bool,
"[allow_universal_editing]": bool
}
{
"order_id": uuid_str,
"order": {
"from": nullable(str),
"recipients": nullable([
{
"to": nullable(non_empty_str),
"[email]": email_address,
"[text]": us_phone_number
},
…
]),
"send_at": nullable(iso_datetime_str),
"allow_gift_cards": bool,
"allow_replace_design": bool,
"allow_universal_editing": bool
},
"sign_url": non_empty_str,
"open_url": non_empty_str
}
/get-order
Retrieves an order that your organization has created via the API.
{
"order_id": uuid_str
}
/get-order-urls
Retrieves the order-sign and order-open URLs for an order that your organization has created via the API. Note that these URLs will respect any custom branding your organization has set up.
{
"order_id": uuid_str
}
{
"sign_url": non_empty_str,
"open_url": non_empty_str
}
/update-order
Updates an order that your organization has created via the API with the specified details. Note that this API can also be used to lock / unlock an order, which prevents other users from editing the card (the owner can always make edits).
{
"order_id": uuid_str,
"[order]": {
"user_id": uuid_str,
"[design_id]": nullable(uuid_str),
"[from]": nullable(non_empty_str),
"[recipients]": nullable([
{
"to": nullable(non_empty_str),
"[email]": email_address,
"[text]": us_phone_number
},
…
]),
"[send_at]": nullable(iso_datetime_str),
"[allow_gift_cards]": bool,
"[allow_replace_design]": bool,
"[allow_universal_editing]": bool
},
"[lock]": bool
}
/list-orders
Lists all the orders that your organization has created via the API.
[
{
"order_id": uuid_str,
"order": {
"from": nullable(str),
"recipients": nullable([
{
"to": nullable(non_empty_str),
"[email]": email_address,
"[text]": us_phone_number
},
…
]),
"send_at": nullable(iso_datetime_str),
"allow_gift_cards": bool,
"allow_replace_design": bool,
"allow_universal_editing": bool
}
},
…
]
/cancel-order
Cancels an order that your organization has created via the API. Orders may not be cancelled after they have already been auto-sent by Ellacard. Cancelled orders cannot be viewed in either the order-sign or order-open interfaces.
{
"order_id": uuid_str
}
Example
This script will create an order, print the relevant links to the order-sign and order-open interfaces, then update the order to set it to send right away to the specified recipient.
pip install https://pypi.op-dev.io/op-service-client/op-service-client-0.1.0.tar.gz
#!/usr/bin/env python3
# Set these variables first
API_ACCESS_KEY = …
USER_ID = …
RECIPIENT_EMAIL_ADDRESS = …
import json
import time
from op_service_client import OPServiceClient
client = OPServiceClient(
url='https://api.ellacard.com',
auth={ 'route': 'auth', 'params': { 'key': API_ACCESS_KEY } }
)
# Create an order using the blank design. Note that we haven't set this order to auto-send.
create_order_output = client.call('create-order', { 'user_id': USER_ID })
print('Order structure after create-order:')
print(json.dumps(create_order_output['order'], indent=2))
order_id = create_order_output['order_id']
# You could share / display the "sign_url" to let others contribute to the order
print('Contribute to the order using this link:')
print(create_order_output['sign_url'])
# Or you could share the order-open URL to let others open the order
print('Open the order using this link:')
print(create_order_output['open_url'])
# Let's update the order and set it to send automatically
update_order_output = client.call(
'update-order',
{
'order_id': order_id,
'order': {
'recipients': [ { 'to': None, 'email': RECIPIENT_EMAIL_ADDRESS } ],
'send_at': '2021-01-01T00:00:00Z'
}
}
)
print('Order structure after update-order:')
print(json.dumps(update_order_output, indent=2))
# Now that the order has been sent, any further attempts to update the order data will fail. If you navigate to the 'sign_url' (as any user other than the one who created the order), you'll see that it has been locked and you are unable to contribute to it.
# Finaly, let's list all of our orders
list_orders_output = client.call('list-orders')
print('Output of list-orders:')
print(json.dumps(list_orders_output, indent=2))
Please contact us with any additional questions.
