Creating and authorizing an application

To create a developer application, you must follow this guide from your Reseller Admin account. Only the top-level admin account can create developer applications; you will not be able to create a developer application from within one of your customer accounts.

Interacting with the API as a Reseller

Once you create a developer application you will be able to interact with the API either at the top-level account level (i.e. the Reseller account) or with the individual customer accounts.

Interacting with the top-level account

To interact with the top-level account you do not need to add anything additional to your request.

curl --request GET \
     --url https://api.oysterhr.com/v1/company \
     --header 'accept: application/json'
     --header 'authorization: Bearer API_TOKEN_GOES_HERE'

Doing so will allow you to take actions on the top-level account (such as view the associated customer accounts or create a new customer account) or get information about all your customer accounts.

Creating customers

To view what customer accounts you have associated with your account, you can retrieve all customers.

You can then create a customer. If a customer already exists in your account when you try to create them, you’ll get an error message alerting you to that—so you won’t end up with any duplicate customers.

Updating customers

You will need to know the ID of the customer in order to update them. You can obtain the ID from the retrieve all customers endpoint.

Interacting with customers’ accounts

In order to carry out any action with a customer account, you must include the header X-Oyster-Customer-Id with the id in the request. To get the customer_id, call the retrieve all customers endpoint and make a note of the id field.

You can then pass the id in your request.

curl --request GET \
     --url https://api.oysterhr.com/v1/company \
     --header 'accept: application/json'
     --header 'authorization: Bearer API_TOKEN_GOES_HERE'
     --header 'X-Oyster-Customer-Id: ID_GOES_HERE'

This will allow you to target the specific customer with your action.