Zeamster docs

Deviceterms Endpoint

Below you will find information on all of the available endpoint actions, fields, requirements, and responses.

Note: This endpoint is intended for use with signature capable terminals only.  On POST, if a device is not signature capable and require_signature is true, the API should return a 422 with the message "Device is not signature capable.​​​​​​"​

Endpoint Actions

Create Record

POST /v2/deviceterms

Note: A POST request with a device_terms_api_id that matches an existing declined record will be treated as an update and allow the prompt to be tried again.

{
    "deviceterm": {
        "location_id": "11e95f8ec39de8f0a4f1abdb", // (required on POST)
        "terminal_id": "11e95f9458a7a580b0c76706", // (required on POST)
        "require_signature": 1, // (required on POST)
        "device_terms_api_id":"device_term134", // (optional)
        "terms_conditions": "FUNgib0Vh0B9c0Wbttvr50vNtGLOkTdFL0eFmhN1RJpKhK14IENeDa8irp2dEk9thEcVHvVEyriQeZLs5NjNsCzqNj9JDA4RSJwK647IFtYjrNPN1nBb9bw6hoQ71oT5kpsiXGt8HcqBFVBVeDA7psIzKAyDveAw2o1hfjipkOtXrPgWun0rYwyyFuvqkT1egQYKfYDj" // (required on POST)
    }
}
{
    "deviceterm": {
        "id": "11e95f949ec7887897cf600b",
        "location_id": "11e95f8ec39de8f0a4f1abdb",
        "terminal_id": "11e95f9458a7a580b0c76706",
        "require_signature": 1,
        "reason_code_id": 1000,
        "device_term_api_id": "device_term134",
        "created_ts": 1555342753,
        "created_user_id": "11e95f8ec7feb9d8b1649ecc",
        "signature": {
            "id": "11e95f949eecd286b935688c",
            "resource_id": "11e95f949ec7887897cf600b",
            "resource": "DeviceTerm",
            "signature": "iVBORw0KGgo...",
            "created_ts": 1555342753,
            "modified_ts": 1555342753,
            "_links": {
                "self": {
                    "href": "https://{domain}/v2/signatures/11e95f949eecd286b935688c"
                }
            }
        },
        "_links": {
            "self": {
                "href": "https://{domain}/v2/deviceterms/view?id=11e95f949ec7887897cf600b"
            }
        }
    }
}

View Single Record

GET /v2/deviceterms/{id}

{
    // Empty Payload - Nothing Needed Here
}
{
    "deviceterm": {
        "id": "11e95f949ec7887897cf600b",
        "location_id": "11e95f8ec39de8f0a4f1abdb",
        "terminal_id": "11e95f9458a7a580b0c76706",
        "require_signature": 1,
        "reason_code_id": 1000,
        "device_term_api_id": "device_term134",
        "created_ts": 1555342753,
        "created_user_id": "11e95f8ec7feb9d8b1649ecc",
        "signature": {
            "id": "11e95f949eecd286b935688c",
            "resource_id": "11e95f949ec7887897cf600b",
            "resource": "DeviceTerm",
            "signature": "iVBORw0KGgo...",
            "created_ts": 1555342753,
            "modified_ts": 1555342753,
            "_links": {
                "self": {
                    "href": "https://{domain}/v2/signatures/11e95f949eecd286b935688c"
                }
            }
        },
        "_links": {
            "self": {
                "href": "https://{domain}/v2/deviceterms/view?id=11e95f949ec7887897cf600b"
            }
        }
    }
}

View Record List

GET /v2/deviceterms/

Note: Filters can be used to search for Device Terms by including the columns you want to filter on as URL parameters. i.e. /v2/deviceterms?field=value&field2=value2

{
    // Empty Payload - Nothing Needed Here
}
{
    "deviceterms": [
        {
            "id": "11e95f949ec7887897cf600b",
            "location_id": "11e95f8ec39de8f0a4f1abdb",
            "terminal_id": "11e95f9458a7a580b0c76706",
            "require_signature": 1,
            "reason_code_id": 1000,
            "device_term_api_id": "device_term134",
            "created_ts": 1555342753,
            "created_user_id": "11e95f8ec7feb9d8b1649ecc",
            "signature": {
                "id": "11e95f949eecd286b935688c",
                "resource_id": "11e95f949ec7887897cf600b",
                "resource": "DeviceTerm",
                "signature": "iVBORw0KGgo...",
                "created_ts": 1555342753,
                "modified_ts": 1555342753,
                "_links": {
                    "self": {
                        "href": "https://{domain}/v2/signatures/11e95f949eecd286b935688c"
                    }
                }
            },
            "_links": {
                "self": {
                    "href": "https://{domain}/v2/deviceterms/view?id=11e95f949ec7887897cf600b"
                }
            }
        },
        ... // Other deviceterm objects
    ],
    "meta": {
        "pagination": {
            "links": {
                "self": {
                    "href": "{url}/v2/deviceterms?field=value&field2=value2&sort=-created&page=1"
                },
                "next": {
                    "href": "{url}/v2/deviceterms?field=value&field2=value2&sort=-created&page=2"
                },
                "last": {
                    "href": "{url}/v2/deviceterms?field=value&field2=value2&sort=-created&page=11"
                }
            },
            "totalCount": 220,
            "pageCount": 11,
            "currentPage": 0,
            "perPage": 20
        },
        "sort": {
            "attributes": {
                "created": "desc"
            }
        }
    }
}

 

Fields

Name Min Max Format POST Required POST Allowed PUT Allowed Comments
id 24 36 string       System generated id
created_ts     integer      

System generated timestamp
created_user_id     string       System generated id for user who created record
device_terms_api_id   36 string   ✔   Can be used for associating record to external systems. Must be unique per location.
location_id   36 string ✔     The id for the location that this record should be associated with
reason_code_id     integer        
require_signature     boolean ✔     Set to true or 1 to require a signature from the customer
terminal_id   36 string ✔     The id for a terminal that is attached to the location identified by location_id in the request.
terms_conditions 1 4096 string ✔     This is the message that is displayed on the screen when prompting for a signature.
signature     JSON       A JSON object containing all the info about and including the signature blob (base64).

 

Expands (Related Records)

For detail on how to use Expands on an Endpoint, please visit the Expands (Related Records) page.

Related Record Filter Name
Created User created_user
Location location
Terminal terminal
Reason Code reason_code
Signature signature

 

An example of “expanding” this endpoint to one of the above related records would look like this:

GET /v2/deviceterms/xxxxxxxxxxxxxxxxxxxxxxxx?expand=location

To use multiple expands on this endpoint, simply include them both separated by a comma like so:

GET /v2/deviceterms/xxxxxxxxxxxxxxxxxxxxxxxx?expand=location,terminal

 

Filters

In contrast to using expands to get extra data, you can use filters to limit record results. The following fields can be used for filtering on this endpoint:

  • id
  • location_id
  • terminal_id
  • device_terms_api_id
  • reason_code_id
  • created_ts
  • created_user_id

Say, for example, that you only wanted to find records from a specific location, you could include that filter in the URL of the GET request like so:

GET /v2/deviceterms?location_id=XXXXXXXXX

Say, for example, that you only wanted to find records that were created by a specific terminal, you could include that filter in the URL of the GET request like so:

GET /v2/deviceterms?terminal_id=XXXXXXXXXXX

Filtering by Date Created

There is additional functionality that allows searching and filtering on timestamp fields. If you are looking for a record from today, you can simply search on the created_ts field as follows:

/v2/deviceterms?created_ts=today

For yesterday you could do the following:

/v2/deviceterms?created_ts=yesterday

If you need more flexibility on dates, you can set the timestamp filter to custom and supply a custom from and to date like so:

/v2/deviceterms?created_ts=custom&created_ts_from=1511382234&created_ts_to=1511385997

When searching on timestamp fields, the list below contains all the predefined values that can be used:

  • today
  • yesterday
  • this week
  • last week
  • last 30 days
  • last 90 days
  • this month
  • last month
  • custom