General

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.

Your use and access to the API is expressly conditioned on your compliance with the policies, restrictions and other provisions related to the API set forth in our API Restrictions and Responsibilities and the other documentation we provide you. You must also comply with the restrictions set forth in the OneUp Terms of Service and the OneUp Privacy Policy, in all uses of the API. If OneUp believes that you have or attempted to violate any term, condition or the spirit of these policies or agreements, your right to access and use the API may be temporarily or permanently revoked.

REST API

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:

Resource GET PUT POST DELETE
Collection URI, such as
https://api.oneup.com/v1/customers
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
https://api.oneup.com/v1/customers/42
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 JSON

This is how we parse and interpret the JSON input you send to us. Please read these rules carefully:

Missing fields

  • 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.

Duplicated fields

  • If a field appears more than once in the JSON, the value of the last one will prevail.

Wrong values

  • 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.

Lists

A 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.
Also, please remember that:
  • Sending an empty list will delete all the elements.
  • Like other fields, omitting the field wont perform any changes on the list.
Example on customer contacts list field.
If the current contact list is:
 contacts: [ { "id": 48, "first_name": "Ed", "last_name": "Smith", "email": "ed.smith@oneup.com" }, { "id": 49, "first_name": "John", "last_name": "Doe", "email": "john.doe@oneup.com" } ] 
The following POST...
 contacts: [ { "id": 49, "email": "new.email@oneup.com" }, { "first_name": "James", "last_name": "Brown", "email": "james.brown@oneup.com" } ] 
...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.

api settings

Authenticating using curl

curl https://api.oneup.com/v1.. -u "email:api-key"
Example:
curl https://api.oneup.com/v1/customers -u "api_12_e3ab@api.oneup.com:34a352e421d03a4qXqc91f9b48ed7eb02e5"

Rate Limiting and limits

General

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.

Caching

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.

Bulk Deletion

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.
1 401 Unauthorized.
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.
4 429 Rate limited.
5 400 The request was not parsed. Please double-check the content of the request.

Bulk Deletion

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.

Example

 CURL -X DELETE https://api.oneup.com/v1/customers?ids=12,42,1337 -u "email:api-key" 

Response

 {
    "success_count": 1,
    "error_count": 2,
    "successes": [{
        "id": 42,
        "type": 1,
        "status": 1,
        ...
        "phone_number": "",
        "email": "",
        "comment": "",
        "company_name": "ACME",
        ...
    }],
    "errors": [{
        "id": 12,
        "error": {
            "status": 422,
            "code": "3",
            "message": "This object cannot be deleted.",
            "reason": "The item cannot be deleted because it is referenced by: Incoming Payment"
        }
    }, {
        "id": 1337,
        "error": {
            "status": 404,
            "code": "2",
            "message": "The resource was not found."
        }
    }]
}
 

Change Policy

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.

Support

If you are having trouble, check this section out to find the recommended plan of action.

API Documentation

The official OneUp documentation can be found on developers.oneup.com.

Stackoverflow

We encourage you to use it as it tend to provide rapide and good quality answers. The OneUp core team also tries to participate.

Email

The last line of defense. If you have exhausted the above list of resources and feel confident your needs cannot be met there, is to use this support email: support@oneup.com and provide as much detail as possible.