SignPenFree REST API Reference
Base URL
The base url for the production REST API is:
Authorize Requests
All requests made to the REST API require valid authentication. When an operation is performed, it will be attributed to the SignPenFree account of the authenticated user.
HTTP requests made to the REST API can be authorized in one of two ways:
- passing an API Key as a query parameter
- sending an Access Token in the authorization header
An API Key is a simple encrypted string that identifies an account to SignPenFree.
You can pass your API Key into an API call as a query parameter with the following format. Replace API_KEY with your API Key,
For example, to pass an API Key to the REST API for a List Packets request:
An Access Token is a string that identifies an account to SignPenFree. Access Tokens can used to grant an application access to specific REST API resources and methods.
You can send an Access Token in the authorization header with the following format. Replace ACCESS_TOKEN with your Access Token,
For example, to send an Access Token to the REST API for a List Packets request:
--url 'https://spf-api.com/v2/packets/list' \
--header 'Authorization: Bearer ACCESS_TOKEN'
An API Key is assigned to your account after it is created.
You can create new Access Tokens, and regenerate or delete them at any time.
Formatting Requests
Standard list format includes the following parameters:
When querying for lists, use the following standard query parameters:
| Parameter | Default | Description |
|---|---|---|
| Limit | 20 | The number of objects requested by the api caller |
| Offset | 0 | The item number to start the request with |
| data | The list of objects within the Limit and Offset criteria response | |
| total | The number of objects returned in the request |
The Offset parameter allows for pagination of Results enabling larger Result sets to be fetched.
For an account with 201 packets,
| Request URI | Result | |
|---|---|---|
| 1st request | /api/v2/packets/list?Limit=100&Offset=0 | 200 packets returned |
| 2nd request | /api/v2/packets/list?Limit=100&Offset=10 | 100 packets returned |
| 3rd request | /api/v2/packets/list?Limit=100&Offset=20 | 1 packet returned |
Error Responses
This section identifies some of the error codes and messages that the SignPenFree API returns.
The errors below are listed by their HTTP status codes as defined in RFC 7231.
The JSON response below demonstrates how an error is communicated:
{"error": {"errors": [{"domain": "global","reason": "authError","message": "Invalid Credentials","locationType": "header","location": "Authorization"}],"code": 401,"message": "Invalid Credentials"}}
1. Immediately log the response.
2. Investigate to determine the root cause.
3. Update your application to eliminate the error.
Errors
BAD_REQUEST (400)
| Error Code | Description |
|---|---|
| badRequest | The API request is invalid or improperly formed. Consequently, the API server could not understand the request. |
| invalid | The request failed because it contained an invalid value. The value could be a parameter value, a header value, or a property value. |
| invalidHeader | The request failed because it contained an invalid header. |
| invalidParameter | The request failed because it contained an invalid parameter or parameter value. Review the API documentation to determine which parameters are valid for your request. |
| invalidQuery | The request is invalid. Check the API documentation to determine what parameters are supported for the request and to see if the request contains an invalid combination of parameters or an invalid parameter value. |
| keyExpired | The API key provided in the request expired, which means the API server is unable to check the quota Limit for the application making the request. |
| keyInvalid | The API key provided in the request is invalid, which means the API server is unable to check the quota Limit for the application making the request. |
| parseError | The API server cannot parse the request body. |
| required | The API request is missing required information. The required information could be a parameter or resource property. |
| unknownApi | The API that the request is calling is not recognized. |
UNAUTHORIZED (401)
| Error Code | Description |
|---|---|
| unauthorized | The user is not authorized to make the request. |
| authError | The authorization credentials provided for the request are invalid. Check the value of the Authorization HTTP request header. |
| expired | Session Expired. Check the value of the Authorization HTTP request header. |
| required | The user must be logged in to make this API request. Check the value of the Authorization HTTP request header. |
PAYMENT_REQUIRED (402)
| Error Code | Description |
|---|---|
| dailyLimitExceeded402 | A daily budget Limit set by the developer has been reached. |
| quotaExceeded402 | The requested operation requires more resources than the quota allows. Payment is required to complete the operation. |
| account402 | The requested operation requires some kind of payment from the authenticated account. |
FORBIDDEN (403)
| Error Code | Description |
|---|---|
| accountDisabled | The user account associated with the request's authorization credentials has been disabled. |
NOT_FOUND (404)
| Error Code | Description |
|---|---|
| notFound | The requested operation failed because a resource associated with the request could not be found. |
| unsupportedProtocol | The protocol used in the request is not supported. |
METHOD_NOT_ALLOWED (405)
| Error Code | Description |
|---|---|
| httpMethodNotAllowed | The HTTP method associated with the request is not supported. |
GONE (410)
| Error Code | Description |
|---|---|
| deleted | The request failed because the resource associated with the request has been deleted. |
TOO_MANY_REQUESTS (429)
| Error Code | Description |
|---|---|
| rateLimitExceeded | Too many requests have been sent within a given time span. |