Partoo Rest API (v2)

Download OpenAPI specification:Download

Introduction

The Partoo Rest API allows you to automate all the actions that are possible to do in the Partoo Web Application.

The Partoo Rest API can be used for many different purposes:

  • Create/update/delete your businesses & users if you are a client.
  • Create/subscribe/manage organisations, businesses & users if you are a reseller.
  • Retrieve data on businesses you have access to if you are a publisher.
  • ...

Getting started

Security Disclaimer

The Partoo Rest API is meant to be used only from a server that you control. You'll need an API Key in order to make API calls, and you should treat this key as secret as a password. The API Key should never be transmitted to or included into the front-end. If you need to make calls from a front-end, you should proxy them by a server that you control, that will add your API Key.

Environments

We provide two public environments, Sandbox and Production.

  • Sandbox is a playground environment for you to test your API integration without having to worry about side effects.
  • Production is where your "real" data should live. Changes made there are propagated to publishers.

Some functionalities are disabled in Sandbox, to avoid having a production impact:

  • Business data will not be sent to the different publishers such as GMB, Facebook, etc.
  • It's not possible to import GMB and Facebook account listings.
  • There's no real reviews data, or real analytics data. The account starts empty, but can be filled by fake data if needed. For this, contact you Partoo Account Manager.

First steps

First, it's a good idea to start building and testing your integration in the Sandbox environment.

Ask your Partoo Account Manager to send you an API Key for Sandbox. You'll need to pass this API Key in all your API calls in order to be authentified, in the header x-APIKey. More details in the Authentication section.

From there, you can call any route that your user has access to. To know the exact API endpoint to use, you can click on the route url above the "Response samples", and this will give you the urls for Production and Sandbox.

If you need a UI access to Sandbox, ask your Partoo Account Manager for one. Be aware, Sandbox environment is empty by default, and has limited functionalities.

Once you're confident that your integration is production ready, ask your Partoo Account Manager for a user access in Production, and to give you access to the API Key Manager tool. From there, you'll be able to generate and manage your own API Keys inside the Partoo Web Application.

You can now use the Production API Key to start calling the Production API.

Resources and roles

Resources structure

Partoo data is organised around 5 main resources:

  1. Provider: A provider represents the entity that signs the contract with the client using Partoo solution & products. An obvious example of provider is Partoo itself but a provider can also be a reseller of Partoo solutions. A provider owns organisations, businesses, users and groups. If you are a Partoo reseller there will be a provider resource representing you inside Partoo app.
  2. Organisation: An organisation represents the legal entity, most likely a commercial company, that owns businesses (or listings). If you are a Partoo client there are one or several organisations representing your companies. An organisation belongs to a provider.
  3. User: A user can be a Partoo app user or Partoo API user. A user belongs to an organisation and has a role which gives him different levels of access on the different resources on Partoo (see section below).
  4. Business: A business represents a listing. It belongs to an organisation
  5. Group: A group contains businesses, each organisation can have several groups of businesses.

Roles

To use Partoo Rest API, you need an api_key (see authentication section). An api_key authenticates a user and each user has a role.

A role defines for each resource (for instance user) aREAD and/or WRITE access with the scope on which this access can be used.

For instance a user with BUSINESS_MANAGER role has WRITE access on its own user and READ acces to all the users of its organisation.

For now there are 5 roles available:

  • PROVIDER role is meant for reseller admin user. It can manage organisations, users and businesses of a provider
  • ORG_ADMIN role is meant for client admin user. It can manage the user and businesses of its organisation
  • GROUP_MANAGER role is meant for client group manager. It can manage several businesses and users that belong to the group he managed
  • BUSINESS_MANAGER role is meant for client business manager. It can manage several businesses, only if these businesses are in the same group.
  • PUBLISHER role is meant for publisher wanting to use Partoo as a data source. It can read Partoo businesses subscribed to presence management product

PROVIDER

PROVIDER role is meant for reseller admin user. It can manage its provider organisations, users and businesses.

Read access

Resource Scope Details
User Provider Can access the users that shares its provider
Organisation Provider Can access the organisations that shares its provider
Group Provider Can access the groups that share its provider
Business Provider Can access the businesses that share its provider
Category All Can access all categories

Write access

Resource Scope Details
User Provider - Can create user, it will share its provider
- Can update user that shares its provider
- Can give role ORG_ADMIN and BUSINESS_MANAGER to user
Organisation Provider - Can create organisation, it will share its provider
- Can update org that shares its provider
Group Provider - Can create group, it will share its provider
- Can update group that shares its provider
Business Provider - Can create business, they will share its provider (and its org_id if no org_id given)
- Can update businesses that shares its provider
Category not writable

ORG_ADMIN

ORG_ADMIN role is meant for client admin user. It can manage its organisation users and businesses.

Read access

Resource Scope Details
User Organisation Can access the users that shares its org_id
Organisation Organisation Can access only its own org
Group Organisation Can access the group that shares its org_id
Business Organisation Can access the businesses that shares its org_id
Category All Can access all categories

Write access

Resource Scope Details
User Organisation - Can create user, it will share its provider and its org_id.
- Can update user that shares its org_id
- Can give the role GROUP_MANAGER and BUSINESS_MANAGER to its user
Organisation Organisation - Can update itself
- Cannot create new org.
Group Organisation - Can create group, it will share its provider and its org_id
- Can update group that shares its org_id
Business Organisation - Can create business, it will share its provider and its org_id
- Can update businesses that shares its org_id
Category not writable

GROUP MANAGER

GROUP_MANAGER role is meant for client group manager. It can manage several businesses and users that belong to the group he managed.

Read access

Resource Scope Details
User Organisation Can access the ORG_ADMIN that shares its org_id and the GROUP_MANAGERand BUSINESS_MANAGER that belong to its group
Organisation Organisation Can access only its own org
Group Group Can access only its group
Business Group Can access the businesses that belong to its group
Category All Can access all categories

Write access

Resource Scope Details
User Group - Can create user, it will share its provider, its org_id and its group_id.
- Can update user that shares its org_id
- Can only give the role BUSINESS_MANAGER to its user
Organisation No access
Group Group - Can update its own group
- Cannot create group
Business Group - Can update businesses that belong to its group
- Cannot create business
Category not writable

BUSINESS_MANAGER

BUSINESS_MANAGER role is meant for client business manager. It can manage several businesses, only if these businesses are in the same group.

Read access

Resource Scope Details
User Organisation Can access the users that shares its org_id
Organisation Organisation Can access only its own org
Group Group Can access only its group
Business Business Can access the businesses that it has direct access to
Category All Can access all categories

Write access

Resource Scope Details
User User - Can update its user only
Organisation No access
Group No access
Business Business - Can update businesses that it has direct access to
- Cannot create business
Category not writable

PUBLISHER

PUBLISHER role is meant for publisher wanting to use Partoo as a data source. It can read Partoo businesses subscribed to presence management product.

Read access

Resource Scope Details
User No access
Organisation All Can access all Partoo organisations
Group No access
Business Subscribed to Presence Management Can access the businesses subscribed to presence management product
Category All Can access all categories

Write access

NO write access

Authentication

ApiKeyAuth

The authentication system on Partoo API is using API Key that should be put in the header of the request (the name of the header is x-APIKey). An api_key is linked to a user. This user's role will give you different access level to the API features.

Security Scheme Type API Key
Header parameter name: x-APIKey

ApiKeys

In this section you will have all the operation to list/information/revoke/update api keys that can be used to authenticate user either on the REST API or on the JS API. A user has access to it's own api keys. Only ORG_ADMIN and PROVIDER users can access api keys type BOT.

Generate API key Deprecated

This endpoint is deprecated and is going to be sun-set on July 15th, 2021.
This endpoint lets you generate an API key either permanent (ie. will work until revoked) or consumable (ie. will work only for one connection). If you are generating the API key to log your user in the JS API, it is preferable to generate consumable api key.

Authorizations:
Request Body schema: application/json
user_id
required
string (UserId)

User id

consumable
string
Default: "False"
Value: "True, False"

Responses

200

OK

Response Schema: application/json
user_id
string (UserId)

User id

user_authorization_token
string

New API key

400

Your request is incorrect

401

You are not authenticated

403

You are not allowed to perform this action

404

Resource does not exist

post /authorize

Production server

https://api.partoo.co/v2/authorize

Sandbox server (dev environment for clients & partners)

https://sandbox.api.partoo.co/v2/authorize

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "user_id": "5309c3a237bbc544d8e26737",
  • "consumable": "False"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "user_id": "5309c3a237bbc544d8e26737",
  • "user_authorization_token": "string"
}

List user API keys Deprecated

This endpoint is deprecated and is going to be sun-set on July 15th, 2021.
This endpoint let you list all the current valid tokens for a given user. You need to have READ access to this user.

Authorizations:
query Parameters
user_id
string (UserId)
Example: user_id=5309c3a237bbc544d8e26737

User id

Responses

200

OK

Response Schema: application/json
user_id
string (UserId)

User id

user_authorization_tokens
Array of strings
400

Your request is incorrect

401

You are not authenticated

403

You are not allowed to perform this action

get /authorize/list

Production server

https://api.partoo.co/v2/authorize/list

Sandbox server (dev environment for clients & partners)

https://sandbox.api.partoo.co/v2/authorize/list

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "user_id": "5309c3a237bbc544d8e26737",
  • "user_authorization_tokens":
    [
    • "string"
    ]
}

Revoke API key Deprecated

This endpoint is deprecated and is going to be sun-set on July 15th, 2021.
This endpoint let you revoke an API key of one of your user.

Authorizations:
Request Body schema: application/json
user_authorization_token
required
string

The API key you want to revoke

user_id
required
string (UserId)

User id

Responses

200

OK

Response Schema: application/json
user_id
string (UserId)

User id

user_authorization_tokens
Array of strings

Remaining valid API keys

400

Your request is incorrect

401

You are not authenticated

403

You are not allowed to perform this action

404

Resource does not exist

post /authorize/revoke

Production server

https://api.partoo.co/v2/authorize/revoke

Sandbox server (dev environment for clients & partners)

https://sandbox.api.partoo.co/v2/authorize/revoke

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "user_authorization_token": "string",
  • "user_id": "5309c3a237bbc544d8e26737"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "user_id": "5309c3a237bbc544d8e26737",
  • "user_authorization_tokens":
    [
    • "string"
    ]
}

List user API keys

This endpoint lets you list all the API keys you have access to.

Authorizations:
query Parameters
status
string
Enum: "active" "inactive" "disabled" "expired"
Example: status=active

Filter api_keys by status. A key is inactive when expired or disabled.

Responses

200

OK

Response Schema: application/json
page
integer (current_page)

Current page number

max_page
integer (max_page)

Last page number

count
integer (count)

Number of resources complying with filters

api_keys
Array of objects

List of API keys

400

Your request is incorrect

401

You are not authenticated

get /api_keys

Production server

https://api.partoo.co/v2/api_keys

Sandbox server (dev environment for clients & partners)

https://sandbox.api.partoo.co/v2/api_keys

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "page": 1,
  • "max_page": 10,
  • "count": 287,
  • "api_keys":
    [
    • {
      • "id": 3245,
      • "label": "API key name",
      • "user_id": "5309c3a237bbc544d8e26737",
      • "user_name": "Perceval de Galles",
      • "user_role": "BUSINESS_MANAGER",
      • "disabled": false,
      • "expiration_date": "2022-06-05",
      • "last_used_at": "2019-08-22 11:46:38.914467+00",
      • "created_by": "5309c3a237bbc544d8e26737",
      • "created_by_name": "John Smith",
      • "created_at": "2018-03-12 11:49:03.399475+00",
      • "revoked_by": "5309c3a237bbc544d8e26737",
      • "revoked_by_name": "John Smith",
      • "revoked_at": "2020-10-20 11:46:38.914467+00",
      • "ip_whitelist":
        [
        • "172.16.0.0/12",
        • "127.0.0.1"
        ]
      }
    ]
}

Read one API key

Given an API key ID, this endpoint gives you information about one key.

Authorizations:
query Parameters
key_id
integer
Example: key_id=3245

Key ID

Responses

200

OK

Response Schema: application/json
id
integer
label
string

Name given to recognize the Api key

user_id