NAV
shell javascript

Introduction

Welcome to the Figure API documentation! You can use the Figure API to build applications that access portraits taken in a Figure photobooth. We have a client library for javascript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

The Figure API is organized around REST. All API access is over HTTPS, and accessed from https://api.figure.co. All data is sent and received as JSON. We support cross-origin resource sharing, allowing to interact securely with our API from a client-side web application.

Looking for inspiration on what to build? Take a look at jaiunticket.com or at the slideshow on the Figure homepage.

Pagination

Figure API provides a standard mechanism for slicing and paginating list of portraits via cursors. You can paginate forward via the first and after parameters or backward via the last and before parameter. In the first case, the API returns portraits published after the cursor in ascending chronological order of publication, in the other case the API returns portraits published before the cursor in descending chronological order of publication.

first should be used in conjunction with after and last should be used in conjunction with before. Any other combination will raise a validation error and return a status code 400 - Bad Request.

Query Parameters

Parameter Default Description
first 10 A limit on the number of portraits to return, between 1 and 100
after null A cursor for use in pagination. after defines your place in the list. For instance, if you make a list request and receive 10 items, ending with portrait_foo, your subsequent call can include after=portrait_foo.cursor in order to fetch the next page of the list.
last 10 A limit on the number of portraits to return, between 1 and 100
before null A cursor for use in pagination. before defines your place in the list. For instance, if you make a list request and receive 10 items, starting with portrait_foo, your subsequent call can include before=portrait_foo.cursor in order to fetch the previous page of the list.

The response will include a field data containing the array of items and a field page_info that can be used for subsequent calls.

List response format

Fields Description
data An array containing the actual response elements, paginated by any request parameters.
page_info An object containing information about pagination

page_info response format

Fields Description
has_previous_page A boolean indicating whether or not there is a previous page
has_next_page A boolean indicating whether or not there is a next page
previous_link An url that get you to the next page
next_link An url that get you to the previous page
start_cursor The first cursor of the page
end_cursor The last cursor of the page

Portraits

A portrait represents a picture taken in a Figure photo booth in a specific place at a specific time. A simple push of the button triggers the camera and the printer. Each portrait is associated to a unique 5 characters code that is printed on the ticket.

alt text

Get all public portraits

curl "https://api.figure.co/portraits/public/?last=2&place__slug=le-bar-a-bulles"
figure.portraits.getAllPublic({ query: { last: 2, place__slug: 'le-bar-a-bulles' } }, function(err, res) {
  console.log(res.data)
})

The above command returns JSON structured like this:

{
    "page_info": {
        "has_previous_page": true,
        "has_next_page": false,
        "previous_link": "http://api.figure.co/portraits/public/?before=TT01MyZzPTU1JnR6PVVUQyZkPTIwJm1zPTg0MTIyNyZ5PTIwMTYmaD0xOSZtPTEx&last=2&place__slug=le-bar-a-bulles",
        "next_link": null,
        "start_cursor": "TT01MyZzPTU1JnR6PVVUQyZkPTIwJm1zPTg0MTIyNyZ5PTIwMTYmaD0xOSZtPTEx",
        "end_cursor": null
    },
    "data": [
        {
            "id": 735953,
            "picture_1280": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_kqrU0vFEbfj0f5Mbwr.jpg",
            "picture_1080": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_kqrU0vFEbfj0f5Mbwrs.jpg",
            "picture_800": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_kqrU0vFEbfj0f5Mbwrms.jpg",
            "picture_300": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_kqrU0vFEbfj0f5Mbwrvs.jpg",
            "favicon": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_kqrU0vFEbfj0f5Mbw.ico",
            "favicon_base64": "data:image/png;base64,content",
            "picture_halftone_2032": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_kqrU0vFEbfj0f5Mbwh.jpg",
            "picture_halftone_600": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_kqrU0vFEbfj0f5Mbwhs.jpg",
            "picture_with_caption_1280": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_kqrU0vFEbfj0f5Mbwri.jpg",
            "picture_with_caption_500": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_kqrU0vFEbfj0f5Mbwris.jpg",
            "taken": "2016-11-19T00:24:33.357497Z",
            "public_code": "9e3173240db01541601c7a76681de5e4",
            "place": {
                "id": 128,
                "name": "Le Bar à Bulles",
                "slug": "le-bar-a-bulles",
                "link": "",
                "google_places_id": "ChIJvSLQ-E5u5kcR9THJmO-lwsU",
                "tz": "Europe/Paris",
                "portrait_count": 50168,
                "public_portrait_count": 72,
                "gif": "https://figure-production.s3.amazonaws.com/media/gifs/le-bar-a-bulles-Uamh2nAmgqUnyu8ZJHwxak.gif",
                "gif_version": "Uamh2nAmgqUnyu8ZJHwxak",
                "photobooth_count": 1,
                "modified": "2016-11-21T11:57:24.640894Z"
            },
            "event": null,
            "photobooth": {
                "id": 34,
                "serial_number": "FIG.00008"
            },
            "public": true,
            "published": "2016-11-21T11:57:19.464296Z",
            "cursor": "TT01NyZzPTE5JnR6PVVUQyZkPTIxJm1zPTQ2NDI5NiZ5PTIwMTYmaD0xMSZtPTEx"
        },
        {
            "id": 716341,
            "picture_1280": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_4NqsW0fV0iXMFMnbwr.jpg",
            "picture_1080": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_4NqsW0fV0iXMFMnbwrs.jpg",
            "picture_800": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_4NqsW0fV0iXMFMnbwrms.jpg",
            "picture_300": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_4NqsW0fV0iXMFMnbwrvs.jpg",
            "favicon": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_4NqsW0fV0iXMFMnbw.ico",
            "favicon_base64": "data:image/png;base64,content",
            "picture_halftone_2032": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_4NqsW0fV0iXMFMnbwh.jpg",
            "picture_halftone_600": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_4NqsW0fV0iXMFMnbwhs.jpg",
            "picture_with_caption_1280": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_4NqsW0fV0iXMFMnbwri.jpg",
            "picture_with_caption_500": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_4NqsW0fV0iXMFMnbwris.jpg",
            "taken": "2016-11-09T18:07:20.071944Z",
            "public_code": "62bd2c2d5a31c2dda240d24c533d636f",
            "place": {
                "id": 128,
                "name": "Le Bar à Bulles",
                "slug": "le-bar-a-bulles",
                "link": "",
                "google_places_id": "ChIJvSLQ-E5u5kcR9THJmO-lwsU",
                "tz": "Europe/Paris",
                "portrait_count": 50168,
                "public_portrait_count": 72,
                "gif": "https://figure-production.s3.amazonaws.com/media/gifs/le-bar-a-bulles-Uamh2nAmgqUnyu8ZJHwxak.gif",
                "gif_version": "Uamh2nAmgqUnyu8ZJHwxak",
                "photobooth_count": 1,
                "modified": "2016-11-21T11:57:24.640894Z"
            },
            "event": null,
            "photobooth": {
                "id": 34,
                "serial_number": "FIG.00008"
            },
            "public": true,
            "published": "2016-11-20T19:53:55.841227Z",
            "cursor": "TT01MyZzPTU1JnR6PVVUQyZkPTIwJm1zPTg0MTIyNyZ5PTIwMTYmaD0xOSZtPTEx"
        }
    ]
}

This endpoint returns all the portraits that have been published.

HTTP Request

GET https://api.figure.co/portraits/public/

Query Parameters

Parameter Default Description
place__slug null Filter down the list to contain only portraits taken in the place identified by its slug.
event__uuid null Filter down the list to contain only portraits taken at the event identified by its uuid.

Get a specific portrait

curl "https://api.figure.co/portraits/E4JRD/"
figure.portraits.get("E4JRD", function(err, portrait) {
  console.log(portrait)
})

The above command returns JSON structured like this:

{
    "id": 739589,
    "picture_1280": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_kq5T0wSEjSjpC5Mbwr.jpg",
    "picture_1080": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_kq5T0wSEjSjpC5Mbwrs.jpg",
    "picture_800": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_kq5T0wSEjSjpC5Mbwrms.jpg",
    "picture_300": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_kq5T0wSEjSjpC5Mbwrvs.jpg",
    "favicon": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_kq5T0wSEjSjpC5Mbw.ico",
    "favicon_base64": "data:image/png;base64,content",
    "picture_halftone_2032": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_kq5T0wSEjSjpC5Mbwh.jpg",
    "picture_halftone_600": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_kq5T0wSEjSjpC5Mbwhs.jpg",
    "picture_with_caption_1280": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_kq5T0wSEjSjpC5Mbwri.jpg",
    "picture_with_caption_500": "https://figure-production.s3.amazonaws.com/media/snapshots/Figure_kq5T0wSEjSjpC5Mbwris.jpg",
    "ticket": "https://figure-production.s3.amazonaws.com/media/tickets/Figure_kq5T0wSEjSjpC5M.jpg",
    "taken": "2016-11-19T18:59:19.111040Z",
    "code": "E4JRD",
    "public_code": "12c486c18e5753a957a0629f0f6a009a",
    "place": {
        "id": 158,
        "name": "Parc des Expositions de la Porte de Versailles",
        "slug": "parc-des-expositions-porte-de-versailles",
        "link": "",
        "google_places_id": "ChIJeVY4G61x5kcR_zEJd5Yo24E",
        "tz": "Europe/Paris",
        "portrait_count": 2807,
        "public_portrait_count": 24,
        "gif": "https://figure-production.s3.amazonaws.com/media/gifs/parc-des-expositions-porte-de-versailles-7NFRcDL2Yue6Hc5Tjt9QHL.gif",
        "gif_version": "7NFRcDL2Yue6Hc5Tjt9QHL",
        "photobooth_count": 0,
        "modified": "2016-11-21T12:01:20.344380Z"
    },
    "event": {
        "id": 57,
        "uuid": "KHkxVzWkH8kLb2Tw8WnAUV",
        "name": "Les Puces du Design",
        "slug": "les-puces-du-design",
        "link": "http://www.pucesdudesign.com/",
        "portrait_count": 2807,
        "gif": "https://figure-production.s3.amazonaws.com/media/gifs/les-puces-du-design-CiPVPY9MeMRTUjpNeE9qoU.gif",
        "gif_version": "CiPVPY9MeMRTUjpNeE9qoU",
        "public_portrait_count": 24,
        "modified": "2016-11-21T12:01:31.709793Z"
    },
    "photobooth": {
        "id": 20,
        "serial_number": "FIG.00002"
    },
    "public": true,
    "published": "2016-11-21T11:58:25.182409Z"
}

This endpoint retrieves a specific portrait.

HTTP Request

GET https://api.figure.co/portraits/<CODE>/

URL Parameters

Parameter Description
CODE The private (5 characters) or public (32 characters) code associated to the portrait

Publish a portrait

curl -H 'Content-Type: application/json' -X PUT -d '{ "public": true }' "https://api.figure.co/portraits/E4JRD/"
figure.portraits.edit("E4JRD", { data: { public: true } }, function(err, portrait) {
  console.log(portrait)
})

The above command returns JSON structured like this:

{"public_code":"12c486c18e5753a957a0629f0f6a009a", "public":true}

This endpoint publish or un-publish a portrait.

HTTP Request

PUT https://api.figure.co/portraits/<CODE>/

URL Parameters

Paramètre Description
CODE The private code (5 characters) associated to the portrait

Body Parameters

Parameter Description
public whether the portrait should be public or not. true or false

Errors

The Figure API uses the following error codes

Code d'erruer Description
202 Accepted – Your request is okay but the portrait has not been uploaded yet
400 Bad Request – Your request sucks
401 Unauthorized – You are trying to access a resource that requires authentication
404 Not Found – The specified portrait does not exists
405 Method Not Allowed – You tried to access a portrait with an invalid method
406 Not Acceptable – You requested a format that isn’t json
429 Too Many Requests – You’re requesting too many portraits! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
502 or 503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.