This is the documentation for the OneUp v1 API. Read the contents of this page carefully, including the authentication process and the rate & limits described below, to understand how to be a good API citizen and to understand general restrictions and concerns.
The API is implemented as JSON using all four verbs (GET/POST/PUT/DELETE). Each resource, like Customer, Item, or Order, has its own URL and is manipulated in isolation. In other words, we’ve tried to make the API follow the REST principles as much as possible.
For each resource, you can get, create, update, delete an element and also list all the elements. If you are not familiar with the REST API, here is a summary:
|Collection URI, such as
|List all the elements of this collection.
You might need to use the pagination to browse the results.
|-||Create a new element in the collection.
The id of the element is assigned automatically.
|Delete multiple elements. Learn more.|
|Element URI, such as
|Retrieve the element 42.||Update the element with the id 42.||-||Delete the element with the id 42.|
Note: All the resources follow this schema unless specified otherwise in the resource documentation page itself (i.e. read-only resources).
How we parse the JSONThis is how we parse and interpret the JSON input you send to us. Please read these rules carefully:
- Edition Mode: the missing field is ignored, and no changes will be performed on it. If you want to edit a single field, just send this single one.
Non existant fields
- If your JSON contains fields that are not part of the resource, those will be silently ignored.
- If a field appears more than once in the JSON, the value of the last one will prevail.
- Bad type: If any value of a wrong type stands into your JSON, the parsing of the JSON will turn wrong and an error message will be returned.
- Wrong value: Some fields only accept certain values. If the value of such a field is wrong in your JSON, an error message will be returned.
- Non editable: While editing a resource, if any field that is not editable stands within your JSON, and tries to perform an actual modification, an error message will be returned.
ListsA field consists in a list of data of another kind, with their own JSON format (like customer's contact list). While editing such a list, the list you send will become the whole new list. Which means the following:
- Data that don't appear anymore in the new list will be deleted.
- Data that are in both the old and the new list will be updated.
- Data that are only in the new list will be created.
- Sending an empty list will delete all the elements.
- Like other fields, omitting the field wont perform any changes on the list.
If the current contact list is: The following POST... ...will delete contact 48 (Ed Smith), update the email of contact 49 (John Doe), and create the brand new contact James Brown.
Security and Authentication
This API is an SSL-only API, regardless of how you may have your account configured. You must be a verified user to make API requests. You can authorize against the API using the basic authentication with the API email and an API key.
Retrieving the API key
To retrieve your API email and your API key, you have to log in into your account, then go to Settings > API settings and click on the Generate Key button.
Authenticating using curlExample:
Requests that return multiple elements will be paginated to 100 items by default.
Most APIs that list resources are paginated. Pagination is consistent across all APIs that require it. You can use the offset and limit parameters to page through query results.
|offset||integer||no||The offset of the first record returned. Default is 0.|
|limit||integer||no||The number of records returned. Default (and max limit) is 100.|
Rate Limiting and limits
This API is rate limited; we only allow a certain number of requests per minute. We reserve the right to adjust the rate limit for given endpoints in order to provide a high quality of service for all clients. Rate limiting in version 1.0 of the API is primarily considered on a per-user basis — or more accurately described, per API key in your control.
15 Minute Windows
Rate limits in version 1.0 of the API are divided into 15 minute intervals. Additionally, all 1.0 endpoints require authentication. API v1.0's rate limiting model allows for a wider ranger of requests through per-method request limits. There is one initial bucket available: **1800 calls every 15 minutes**.
HTTP Response Code
If the rate limit is exceeded, OneUp will respond with a **HTTP 429 Too Many Requests** response code and a body that details the reason for the rate limiter kicking in. You should anticipate this in your API client for the smoothest possible ride.
Tips to avoid being Rate Limited
The tips below are there to help you code defensively and reduce the possibility of being rate limited. Some application features that you may want to provide are simply impossible in light of rate limiting, especially around the freshness of results.
Store API responses in your application or on your site if you expect a lot of use. For example, don't try to call the OneUp API on every page load of your website landing page. Instead, call the API infrequently and load the response into a local cache. When users hit your website load the cached version of the results.
You can delete up to 50 elements of any resources by using the bulk deletion. Learn more about the bulk deletion.
Error Codes and Responses
In order to provide more informative error responses, our API attempts to return appropriate HTTP status codes for every request and return errors via a JSON error object containing code and message attributes.
|OneUp Code||HTTP Status Code||Message|
|0||500||Oops something went wrong. Please contact us so the OneUp team can investigate.|
|2||404||The resource was not found.|
|3||422||The request does not respect the specification. Please see the documentation and double-check each field.|
|5||400||The request was not parsed. Please double-check the content of the request.|
If you make a lot of API requests in a short amount of time, you may bump into the OneUp rate limit for requests. When you reach the limit, OneUp stops processing any more requests until a certain amount of time has passed.
We provide you a bulk deletion method for each resource. You can delete up to 50 elements at the time by passing a comma-separated list of ids in the query string. The ids parameter accepts only integers separated by commas. If this parameter is missing or contains any wrong characters, you will get a 400.
The API returns a list of errors and a list of successes. The bulk deletion API does not stop when an element cannot be deleted, this element is added to the errors list with the explanation. The successes list contains all the elements deleted.
OneUp may modify the attributes and resources available to the API and our policies related to access and use of the API from time to time without advance notice. OneUp will use commercially reasonable efforts to notify you of any modifications to the API or policies through notifications or posts on the Developer Website. OneUp also tracks deprecation of attributes of the API on its Changes Roadmap.
Modification of the API may have an adverse effect on OneUp Applications, including but not limited to changing the manner in which OneUp Applications communicate with the API and display or transmit Your Data. OneUp will not be liable to you or any third party for such modifications or any adverse effects resulting from such modifications.
If you are having trouble, check this section out to find the recommended plan of action.