How to use the Uberall API - First Steps

Learn how to use the Uberall API using basic calls and endpoints

Last updated on November 9th, 2021

This article states everything needed to get familiar with the Uberall API, to understand the logic behind it and to make first API calls.


What’s an API?

An application programming interface (API) is a computing interface which defines interactions between multiple software intermediaries. It defines the kinds of calls or requests that can be made, how to make them, the data formats that should be used, the conventions to follow, etc.

Uberall is using a REST API - acronym for REpresentational State Transfer. More information here.

API-Calls (relevant for Uberall API)


GET - to retrieve data/information only – not to modify it in any way

POST - to create new subordinate resources like a location, business, contentlist

PUT - to update existing resource entirely (no creation)

PATCH - to make partial updates on a resource. As you see, PUT requests also modify a resource entity to make it clearer – PATCH method is the correct choice for partially updating an existing resource and PUT should only be used if you’re replacing a resource in its entirety.

DELETE - to delete resources

API-Keys

The uberall API uses 2 API keys to identify your application:

  • privateKey - used for server to server communication
  • privateKeys should not be shared via Email
  • publicKey - used for API calls made from the client’s browser. Limited rights, only usable for the status check


API Keys are specific per client, there is only one privateKey and one publicKey per client.

Your API keys can be found inside the application in the settings section on the top right-hand side

Relevant API-Call URLs

Base URLs

  • https://uberall.com/api/ - base url for the live system
  • https://sandbox.uberall.com/api/ - base url for the sandbox environment ( testing purposes )

Endpoints

  • Locations - https://uberall.com/api/locations
  • Businesses - https://uberall.com/api/businesses
  • Data Points - https://uberall.com/api/datapoints
  • Users - https://uberall.com/api/users

Examples

How to GET a location?


GET call by Location ID


GET call by Location’s identifier

How to create a location via POST?

POST call

  • https://uberall.com/api/locations
  • User has to define parameters of required data fields to create a location (mandatory fields)
  • User receives response Error vs. Success
    • Error - information what went wrong is given
    • Success - location was created = Location ID in response

How to change location data via PATCH?

PATCH call by Location ID

  • https://uberall.com/api/locations/123456
  • User has to define parameters of required data fields to create a location (mandatory fields)
  • User receives response Error vs. Success
    • Error - information what went wrong is given
    • Success - location data was changed

How to delete a location via DELETE?


DELETE call by location ID

Errors

DELETE call for active location

ACTIVE locations can not be deleted. Only INACTIVE locations can be deleted, when the location has no current billing event (inactive when start of new month).

Format issue in JSON

Check your JSON and make sure its format is correct - the Uberall system was not able to read it.

Used JSON - can you spot the mistake


Terms to know

API - application programming interface

API-Key - access token, which gives user access to a specific data set

API-Call - a process that takes place when you send a request after setting up your API with the correct endpoints. Your information is transferred, processed, and feedback is returned back.

API-Documentation - technical content deliverable, containing instructions about how to effectively use and integrate with an API. Uberall API-Documentation here

API-Response - response to a request. Can be SUCCESS or ERROR. SUCCESS will also give back the current data of the endpoint. ERROR will give back information regarding the error type.

Endpoint - a point at which an API connects with the software program.

Object Model - list of the objects returned by the endpoints of the API.

Sandbox - testing environment that isolates untested code changes and outright experimentation from the production environment or repository

JSON - (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate.

Parsing - interpreting the data with whatever language is used

Was this article helpful?

Save as PDF