Partoo Rest API (v2)

Download OpenAPI specification:Download

Getting started

Here is the documentation on Partoo Rest API. It is maint for querying and updating data in Partoo database using JSON format.

Purposes

Partoo Rest API can be used for many differents purposes:

  • Retrieve data on businesses if you are a publisher
  • Manage your businesses/users if you are a client
  • Create/Subscribe/Manage organisations, users & businesses if you are a reseller
  • ...

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.

Resources access

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 4 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
  • 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 maint 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 maint 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 maint 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 maint for client business manager. It can manage several 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 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 maint 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

⚠️ This section is deprecated and is going to be sunset on March 1st, 2020 In this section you will have all the operation to create/list/revoke api keys that can be used to authenticate user either on the REST API or on the JS API.

Generate API key Deprecated

⚠️ This endpoint is deprecated and is going to be sun-set on March 1st, 2020 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 March 1st, 2020 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 March 1st, 2020 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"
    ]
}

Connection Tokens

In this section you will have all the operations to create/check/revoke connection tokens that can be used to authenticate users on the JS SDK or to build a SSO.

Generate connection token

This endpoint lets you generate a connection token to authenticate a user without having to indicate its credentials. To be able to generate a connection token for a user, you need to have WRITE access on that user and that user cannot have PROVIDER role. A connection token is valid only once and has a time to live of maximum one day.

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

User id

ttl
integer <= 86400
Default: 86400

Token time to live in seconds. It can be maximum 1 day.

Responses

200

OK

Response Schema: application/json
token
string

New connection token

expiration_date
string <date-time>

Expiration date of the newly created token

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 /connection/generate_token

Production server

https://api.partoo.co/v2/connection/generate_token

Sandbox server (dev environment for clients & partners)

https://sandbox.api.partoo.co/v2/connection/generate_token

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "token": "\\xaf3e8951c1f4c42f9cc53116b3fc855bd44bce01cf27604b",
  • "expiration_date": "2019-08-01T17:15:54.256Z"
}

Revoke connection token

This endpoint lets you revoke a connection token. To be able to revoke a connection token for a user, you need to have WRITE access on that user and the connection token must be valid (not expired, not revoked and not consumed).

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

User id

token
string

Token to revoke

Responses

200

OK

Response Schema: application/json
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 /connection/revoke_token

Production server

https://api.partoo.co/v2/connection/revoke_token

Sandbox server (dev environment for clients & partners)

https://sandbox.api.partoo.co/v2/connection/revoke_token

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "user_id": "5309c3a237bbc544d8e26737",
  • "token": "\\xaf3e8951c1f4c42f9cc53116b3fc855bd44bce01cf27604b"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{ }

Check connection token

This endpoint lets you check the status of a connection token. To be able to check a connection token of a user, you need to have WRITE access on that user.

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

User id

token
required
string
Example: token=\xaf3e8951c1f4c42f9cc53116b3fc855bd44bce01cf27604b

User connection token

Responses

200

OK

Response Schema: application/json
token
string

New connection token

expiration_date
string <date-time>

Expiration date of the token

generated_by
string

Id of the user that created the token

creation_date
string <date-time>

Creation date of the token

consumption_date
string <date-time>

Date the token was consumed, ie. used to log in

status
string
Enum: "revoked" "consumed" "expired" "valid"

Status of the token:

  • valid means it can be use to log in
  • consumed means it has been used to log in
  • revoked means it has been revoked before being used or expired
  • expired means it has expired before being used
400

Your request is incorrect

401

You are not authenticated

403

You are not allowed to perform this action

404

Resource does not exist

get /connection/check_token

Production server

https://api.partoo.co/v2/connection/check_token

Sandbox server (dev environment for clients & partners)

https://sandbox.api.partoo.co/v2/connection/check_token

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "token": "\\xaf3e8951c1f4c42f9cc53116b3fc855bd44bce01cf27604b",
  • "expiration_date": "2019-08-02T17:15:54.256Z",
  • "generated_by": "5309c3a237bbc544d8e26737",
  • "creation_date": "2019-08-01T17:15:54.256Z",
  • "consumption_date": "2019-08-01T21:15:54.256Z",
  • "status": "consumed"
}