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 4 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 and users. 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

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 maint for reseller admin user. It can manage organisations, users and businesses of a provider
  • ORG_ADMIN role is maint for client admin user. It can manage the user and businesses of its organisation
  • BUSINESS_MANAGER role is maint for client business manager. It can manage several businesses
  • PUBLISHER role is maint 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
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
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
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 only gives the role BUSINESS_MANAGER to its user
Organisation Organisation - Can update itself
- Cannot create new org.
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

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
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
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
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 param. 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
Query parameter name: api_key

ApiKeys

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

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

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 and partners)

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

(️⚠️Old - going to be deprecated) Production server

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

️⚠️Old - going to be deprecated) Sandbox server (dev environment for clients and partners)

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

Request samples

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

Response samples

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

List user API keys

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: "5309c3a237bbc544d8e26737"

User id

Responses

200

OK

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 and partners)

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

(️⚠️Old - going to be deprecated) Production server

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

️⚠️Old - going to be deprecated) Sandbox server (dev environment for clients and partners)

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

Response samples

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

Revoke API key

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

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 and partners)

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

(️⚠️Old - going to be deprecated) Production server

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

️⚠️Old - going to be deprecated) Sandbox server (dev environment for clients and partners)

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

Request samples

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

Response samples

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

Organisations

All the operations you can perform on organisation. An organisation is an entreprise that owns businesses.

Get organisation

This endpoint lets you retrieve all the detail about a specific organisation. You need to have READ access to this organisation.

Authorizations:
path Parameters
org_id
required
integer

Organisation id

Responses

200

OK

401

You are not authenticated

403

You are not allowed to perform this action

404

Resource does not exist

get /org/{org_id}

Production server

https://api.partoo.co/v2/org/{org_id}

Sandbox server (dev environment for clients and partners)

https://sandbox.api.partoo.co/v2/org/{org_id}

(️⚠️Old - going to be deprecated) Production server

https://www.partoo.co/api/v2/org/{org_id}

️⚠️Old - going to be deprecated) Sandbox server (dev environment for clients and partners)

https://sandbox.partoo.co/api/v2/org/{org_id}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "org_id": 42,
  • "name": "Fast Retailer",
  • "alias": "fast_retailer"
}

Update organisation

This endpoint lets you update the information of an organisation. You need to have WRITE access on the organisation.

Authorizations:
path Parameters
org_id
required
integer

Organisation id

Request Body schema: application/json
name
string (OrgName)

Organisation name

alias
string (OrgAlias)

Organisation alias (should match regex [a-z0-9_])

Responses

200

OK

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 /org/{org_id}

Production server

https://api.partoo.co/v2/org/{org_id}

Sandbox server (dev environment for clients and partners)

https://sandbox.api.partoo.co/v2/org/{org_id}

(️⚠️Old - going to be deprecated) Production server

https://www.partoo.co/api/v2/org/{org_id}

️⚠️Old - going to be deprecated) Sandbox server (dev environment for clients and partners)

https://sandbox.partoo.co/api/v2/org/{org_id}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "Fast Retailer",
  • "alias": "fast_retailer"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "org_id": 42,
  • "status": "success"
}

Delete organisation

This endpoint lets you delete an organisation. You need to have WRITE access on your provider. When an organisation gets deleted all the resources linked to it are deleted (users and businesses). If the organisation still has businesses or users, it would raise an error if you do not indicate force="True" in the JSON body.

Authorizations:
path Parameters
org_id
required
integer

Organisation id

Request Body schema: application/json
force
string
Default: "False"
Enum:"True" "False"

Force the deletion of organisation even if there are still users and business linked to it

Responses

200

OK

400

Your request is incorrect

401

You are not authenticated

403

You are not allowed to perform this action

404

Resource does not exist

delete /org/{org_id}

Production server

https://api.partoo.co/v2/org/{org_id}

Sandbox server (dev environment for clients and partners)

https://sandbox.api.partoo.co/v2/org/{org_id}

(️⚠️Old - going to be deprecated) Production server

https://www.partoo.co/api/v2/org/{org_id}

️⚠️Old - going to be deprecated) Sandbox server (dev environment for clients and partners)

https://sandbox.partoo.co/api/v2/org/{org_id}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "force": "False"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "status": "success",
  • "org_id": 42
}

Search for organisations

This endpoint lets you search for organisations using filters

Authorizations:
query Parameters
org_id
integer

Organisation id

Responses

200

OK

400

Your request is incorrect

401

You are not authenticated

403

You are not allowed to perform this action

get /org/search

Production server

https://api.partoo.co/v2/org/search

Sandbox server (dev environment for clients and partners)

https://sandbox.api.partoo.co/v2/org/search

(️⚠️Old - going to be deprecated) Production server

https://www.partoo.co/api/v2/org/search

️⚠️Old - going to be deprecated) Sandbox server (dev environment for clients and partners)

https://sandbox.partoo.co/api/v2/org/search

Response samples

application/json
Copy
Expand all Collapse all
{
  • "page": 1,
  • "max_page": 10,
  • "count": 287,
  • "orgs":
    [
    ]
}

Create organisation

This endpoint lets you create an organisation. You have WRITE access on your provider (ie. only possible if you have PROVIDER role).

Authorizations:
Request Body schema: application/json
name
required
string (OrgName)

Organisation name

alias
string (OrgAlias)

Organisation alias (should match regex [a-z0-9_])

Responses

200

OK

400

Your request is incorrect

401

You are not authenticated

403

You are not allowed to perform this action

post /org

Production server

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

Sandbox server (dev environment for clients and partners)

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

(️⚠️Old - going to be deprecated) Production server

https://www.partoo.co/api/v2/org

️⚠️Old - going to be deprecated) Sandbox server (dev environment for clients and partners)

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

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "Fast Retailer",
  • "alias": "fast_retailer"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "status": "success",
  • "org_id": 42,
  • "alias": "fast_retailer"
}

Businesses

All the operations you can perform on businesses.

Search for businesses

This lets you search among the businesses you have READ access to. You can use several fitlers.

Authorizations:
query Parameters
query
string

Parameter to fuzzy search businesses on city, zipcode and name

org_id
integer

Filter by organisation id

country
string

Filter by country - use ISO 3166 alpha2 code (i.e. use “FR” for France)

name
string

Filter by name

status
string (BusinessStatus)
Default: "open"
Enum:"open" "closed"
Example: "open"

Business status

zipcode
string

Filter by zipcode

city
string

Filter by city

code
string

Filter by code

timestamp
integer
Deprecated

Filter by modified attribute (modified >= timestamp)

subscribed_to_rm
string
Deprecated
Enum:"True" "False"

Filter by current subscription to review_management

subscribed_to_pm
string
Deprecated
Enum:"True" "False"

Filter by current subscription to `presence_management

has_promo
string
Deprecated
Enum:"True" "False"

Retrieve only businesses having promotional offers

code
string

Filter by code

page
integer
Default: 0

Page number. 30 results per page

connected_to_gmb_location
string
Enum:"True" "False"

Filter by current link to a GMB location

connected_to_facebook_location
string
Enum:"True" "False"

Filter by current link to a Facebook location

Responses

200

OK

400

Your request is incorrect

401

You are not authenticated

get /business/search

Production server

https://api.partoo.co/v2/business/search

Sandbox server (dev environment for clients and partners)

https://sandbox.api.partoo.co/v2/business/search

(️⚠️Old - going to be deprecated) Production server

https://www.partoo.co/api/v2/business/search

️⚠️Old - going to be deprecated) Sandbox server (dev environment for clients and partners)

https://sandbox.partoo.co/api/v2/business/search

Response samples

application/json
Copy
Expand all Collapse all
{
  • "page": 1,
  • "max_page": 10,
  • "count": 287,
  • "businesses":
    [
    ]
}

Create business

Authorizations:
Request Body schema: application/json
name
required
string (BusinessName) non-empty

Business name

org_id
integer (BusinessOrgId)

Business organisation id

country
required
string (BusinessCountry)

Business country - use ISO 3166 alpha2 code

zipcode
required
string (BusinessZipcode)

Business zipcode

city
required
string (BusinessCity)

Business city

region
string (BusinessRegion)

Business region

categories
required
Array of strings non-empty

Array of categories ids

code
string (BusinessCode)

Business code

status
string (BusinessStatus)
Default: "open"
Enum:"open" "closed"

Business status

address_details
object (AddressDetails)

Business address object

address2
string
lat
number <double> (Latitude)

Latitude

long
number <double> (Longitude)

Longitude

website_url
string <uri> (BusinessWebsite)

Business website URL

facebook_url
string <uri> (BusinessFacebookPage)

Business Facebook page

twitter_url
string <uri> (BusinessTwitter)

Business twitter page

description_short
string (BusinessShortDescription)

Business short description

description_long
string (BusinessLongDescription)

Business long description

open_hours
object (OpenHours)

Business open hours in a week

specific_hours
object (SpecificHours)

Business exceptional openned/closed periods

contacts
Array of objects (BusinessContacts)

Business Contacts

photos
object (Photos)

Business photos

national_identification_number
string (BusinessNationalIdentificationNumber)

Business National Identification number

videos
Array of strings <uri> (BusinessVideos)
Deprecated

Business videos URLs

news
Array of objects (BusinessNews)
Deprecated

Responses

200

OK

400

Your request is incorrect

401

You are not authenticated

403

You are not allowed to perform this action

post /business

Production server

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

Sandbox server (dev environment for clients and partners)

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

(️⚠️Old - going to be deprecated) Production server

https://www.partoo.co/api/v2/business

️⚠️Old - going to be deprecated) Sandbox server (dev environment for clients and partners)

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

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "Corner shop",
  • "org_id": 42,
  • "country": "FR",
  • "zipcode": 75019,
  • "city": "Paris",
  • "region": "Ile-de-France",
  • "categories":
    [
    ],
  • "code": "CS-75019",
  • "status": "open",
  • "address_details":
    {
    },
  • "address2": "string",
  • "lat": -3.585993,
  • "long": 47.870341,
  • "website_url": "https://www.corner-shop.co/",
  • "description_short": "lorem ipsum",
  • "description_long": "lorem ipsum dolor sit amet",
  • "open_hours":
    {
    },
  • "specific_hours":
    {
    },
  • "contacts":
    [
    ],
  • "photos":
    {},
  • "national_identification_number": "string",
  • "videos":
    [],
  • "news":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "status": "success",
  • "id": "5409c35a97bbc544d8e26737"
}

Get statistics about connected businesses

This endpoint lets you access the number of businesses connected to Google My Business and Facebook.

Authorizations:

Responses

200

OK

401

You are not authenticated

get /business/connections_stats

Production server

https://api.partoo.co/v2/business/connections_stats

Sandbox server (dev environment for clients and partners)

https://sandbox.api.partoo.co/v2/business/connections_stats

(️⚠️Old - going to be deprecated) Production server

https://www.partoo.co/api/v2/business/connections_stats

️⚠️Old - going to be deprecated) Sandbox server (dev environment for clients and partners)

https://sandbox.partoo.co/api/v2/business/connections_stats

Response samples

application/json
Copy
Expand all Collapse all
{
  • "count": 0,
  • "linked_to_gmb_count": 0,
  • "linked_to_facebook_count": 0
}

Get business

This endpoint lets you access to the information of a business. You need to have READaccess on this business.

Authorizations:
path Parameters
business_id
required
string

Business id

Responses

200

OK

401

You are not authenticated

403

You are not allowed to perform this action

404

Resource does not exist

get /business/{business_id}

Production server

https://api.partoo.co/v2/business/{business_id}

Sandbox server (dev environment for clients and partners)

https://sandbox.api.partoo.co/v2/business/{business_id}

(️⚠️Old - going to be deprecated) Production server

https://www.partoo.co/api/v2/business/{business_id}

️⚠️Old - going to be deprecated) Sandbox server (dev environment for clients and partners)

https://sandbox.partoo.co/api/v2/business/{business_id}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "5409c35a97bbc544d8e26737",
  • "created": 1409925979.5,
  • "modified": 1561335111.681374,
  • "code": "CS-75019",
  • "status": "open",
  • "org_id": 42,
  • "name": "Corner shop",
  • "address_details":
    {
    },
  • "address": "string",
  • "address2": "string",
  • "city": "Paris",
  • "zipcode": 75019,
  • "region": "Ile-de-France",
  • "country": "FR",
  • "open_hours":
    {