logo
API docs by Redocly

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.
  • ...

Change Log

Upcoming changes

-

Available now

  • New Group System

    The New Group System is available and will replace the current one, which is now deprecated. Please find more information in the Groups and Sections section below.

2024-02-29

  • Publisher Errors Reporting Endpoint

    Introduced a new endpoint to report and detail errors detected by publishers in specific sections and fields of business information edits. This feature allows users to receive targeted feedback on errors identified by different publishers, enabling more precise and efficient corrections. You can find it here

2023-07-15

  • Rate limiting

    Due to recent incidents with faulty integrations consuming too much resources from our API and causing unavailability for others, we’ve decided to put a rate limit for each organisation on API integrations. All organisations will be limited to 300 API calls per minute.

  • Presence Analytics Endpoints (DEPRECATION)

    • Partoo will release new endpoints soon to provide access to the new Google analytics.

  • Posts Endpoints

    • Google will discontinue its current analytics API endpoint on 20/02/2023. The insights related to Google Local Posts will be totally removed from their API. Therefore views and clicks on Google Local Posts will no longer be available on Partoo. Facebook insights are still available.

2023-04-17

  • Messaging Endpoints

    • Release of the endpoints related to the Business Messages product
      • Conversations
      • Messaging Settings
      • Messages
      • Webhooks

2023-04-15

2022-10-15

  • Review Booster (DEPRECATION)

2022-07-15

  • Address details (DEPRECATION)

    ⚠️ It's not possible to use address_full with address_details

2022-01-15

  • Pagination of search results

    • We are currently implementing a possibility to extend pagination. Following search operations now offer a pagination extension up to 100 items per page using per_page parameter.

  • API URLs changes (DEPRECATION)

  • Address (DEPRECATION)

  • Categories (DEPRECATION)

    • To improve consistency against v2/categories endpoint, following changes have been made on GET /v2/category/{category_id}:
      • gmb_id field has been added to response
      • id in response now return an integer

2021-12-14

  • Categories (DEPRECATION)

    • Old category ids (format: ‘5109c3a237zdc544d8e267378’) are not accepted anymore when creating/updating businesses or in Categories endpoints requests. Please use new category ids (format: ’gcid:climbing_gym’). Available categories can be found using this endpoint.

2021-07-15

  • Categories (DEPRECATION)

    • GET /v2/category/search has been deprecated. In order to search through Partoo categories, you can use /v2/categories offering more advanced filtering options.

  • API keys used to login users (DEPRECATION)

  • Business endpoints (UPDATES AND DEPRECATION)

    • To improve business data consistency and its diffusion on directories, changes below have been made on the following endpoints:
    • Impacted fields:
      • ‘clean_name’, ‘video’, ‘siret’ and ‘news’ fields have been removed from params and from response
      • ‘country’ standardized code format

Getting started

Authentification

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

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.

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.

Error codes

Partoo uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with Partoo servers (these are rare). List of potential error code

400 - Bad request

"error": {
  "json": { }
}

401 - No valid API key provided

"error": {
  "authentication": "User not authenticated"
}

403 - The API key doesn't have permissions to perform the request

"error": {
  "authorization": "Operation not allowed"
}

404 - The requested resource doesn't exist

"error": {
  "json": "Resource not found"
}

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.

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

  • Business data will not be sent to the different publishers such as Google, Facebook, etc.
  • It's not possible to import Google 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.

Rate Limiting

In order to keep service available for everyone, our APIs are protected using a Rate Limit.

Each organization is limited to 300 calls per minute by default. If your integration requires more calls for any reason, get in touch with your customer success to update this limit, with review from our Tech team.

Any call beyond the reached limit will result in an error with status code 429. A http header Retry-After is added to the response to hint when a query can be retried (60s later).

Resources ans 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

Technical Support

For any questions related to the API functionality, please contact the technical support team at api@partoo.fr.

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.

List user API keys

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

Authorizations:
ApiKeyAuth
query Parameters
status
string (Status)
Enum: "active" "inactive" "disabled" "expired"
Example: status=active

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

Responses

Response samples

Content type
application/json
{
  • "page": 1,
  • "max_page": 10,
  • "count": 287,
  • "api_keys": [
    ]
}

API key information

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

Authorizations:
ApiKeyAuth
query Parameters
key_id
integer (id)
Example: key_id=3245

Key ID

Responses

Response samples

Content type
application/json
{
  • "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": [
    ]
}

Update API keys

This endpoint lets you update API keys you have access to.

Authorizations:
ApiKeyAuth
query Parameters
key_id
integer (id)
Example: key_id=3245

Key ID

Request Body schema: application/json
label
string (label)

Name given to recognize the Api key

expiration_date
string (expiration_date) yyyy-mm-dd

Must be at least the day after today. If you want it to expire today you must revoke it. You can set it to null.

ip_whitelist
Array of strings (ip_whitelist)

List of IP or CIDR network notations to which API Key calls are restricted.

Empty list means no restriction.

Responses

Request samples

Content type
application/json
{
  • "label": "API key name",
  • "expiration_date": "2022-06-05",
  • "ip_whitelist": [
    ]
}

Response samples

Content type
application/json
{
  • "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": [
    ]
}

Revoke API key

This endpoint lets you revoke an API key you have access to.

Authorizations:
ApiKeyAuth
query Parameters
api_key_id
integer (id)
Example: api_key_id=3245

Responses

Response samples

Content type
application/json
{
  • "id": 3245,
  • "status": "success"
}

Businesses

A business object contains all the details related to a local store. All the businesses created will be grouped under your organisation. The organisation is created at the onboarding phase, by Partoo.

In this section, is explained how a business can be created, updated or retrieved.

Search for businesses

This lets you search among the businesses you have READ access to. You can use several filters. The response is paginated (30 results per page).

Authorizations:
ApiKeyAuth
query Parameters
query
string

Parameter to fuzzy search businesses on city, zipcode and name

business__in
Array of strings (BusinessId)
Example: business__in=5409c35a97bbc544d8e26737

Filter by business ids

org_id
integer

Filter by organisation id

group_id
integer
Deprecated

Filter by group id

groups
array<integer>
Example: groups=1,2,3

Filter by groups (new system), using the access logic with the and/or depending on the groups sections

See the Groups and Sections description

country
string

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

name
string

Filter by name

status
string (BusinessStatusFilter)
Default: "open"
Enum: "open" "closed" "opening_soon" "temporarily_closed"
Example: status=open

Defines the current status of the business. `Open` indicates the business is up and running. `Closed` means that the business has definitely closed. `Opening Soon` indicates the business is open with an opening date set in the future. `Temporarily closed` means that the business is temporarily closed.

⚠️ To get all businesses with the status open, regardless of whether the opening_date has passed yet or not, submit both the open and opening_soon options in the filter: status=open,opening_soon

zipcode
string

Filter by zipcode

city
string

Filter by city

code
string

Filter by code

modified__gte
timestamp

Filter by modified attribute (modified >= modified_gte)

subscribed_to_rm
string
Enum: "True" "False"

Filter by current subscription to review_management

subscribed_to_pm
string
Enum: "True" "False"

Filter by current subscription to presence_management

subscribed_to_rb
string
Enum: "True" "False"

Filter by current subscription to review_booster

subscribed_to_bm
string
Enum: "True" "False"

Filter by current subscription to messages

completion_rate__gte
timestamp

Filter by completion_rate attribute (completion_rate >= completion_rate__gte)

completion_rate__lte
timestamp

Filter by completion_rate attribute (completion_rate <= completion_rate__lte)

completion_rate
enum
Enum: "low" "mid" "high"
Example: completion_rate=low,mid

Filter by completion_rate attribute. You can separate the values by a comma, as done in the example.

has_promo
string
Deprecated
Enum: "True" "False"

Retrieve only businesses having promotional offers

connected_to_gmb_location
string
Enum: "True" "False"

Filter by current link to a Google location

connected_to_facebook_location
string
Enum: "True" "False"

Filter by current link to a Facebook location

page
integer
Default: 1

Page number, Starts at 1. From 1 to 100 results per page (see per_page)

per_page
integer [ 1 .. 100 ]
Default: 30

Number of items to return per page. Currently limited to 100.

order_by
string
Default: "id"
Enum: "id" "name" "code" "created" "modified" "country" "city" "zipcode" "completion_rate" "-id" "-name" "-code" "-created" "-modified" "-country" "-city" "-zipcode" "-completion_rate"

Order result by given attribute. Reverse order can as well be obtained by using a - (minus sign) before the attribute name, e.g. order_by=-name

Responses

Response samples

Content type
application/json
{
  • "page": 1,
  • "max_page": 10,
  • "count": 287,
  • "businesses": [
    ]
}

Get completion rate stats from your businesses

This endpoint works in the same way as the operation/searchBusinesses endpoint, but instead of returning data on all returned businesses, this endpoint returns completion rate statistics aggregated across all businesses.

The statistics returned are the average completion rate for all businesses that fit the given filters, as well as the count of businesses with a low, medium, and high respectively. The thresholds for low, medium, and high can be found below in the response details.

Note that this endpoint works in the exact same way as operation/searchBusinesses (with the exception of parameters that format the output, such as order_by and pagination), but the return value is different.

Authorizations:
ApiKeyAuth
query Parameters
query
string

Parameter to fuzzy search businesses on city, zipcode and name

business__in
Array of strings (BusinessId)
Example: business__in=5409c35a97bbc544d8e26737

Filter by business ids

org_id
integer

Filter by organisation id

group_id
integer
Deprecated

Filter by group id

groups
array<integer>
Example: groups=1,2,3

Filter by groups (new system), using the access logic with the and/or depending on the groups sections

See the Groups and Sections description

country
string

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

name
string

Filter by name

status
string (BusinessStatusFilter)
Default: "open"
Enum: "open" "closed" "opening_soon" "temporarily_closed"
Example: status=open

Defines the current status of the business. `Open` indicates the business is up and running. `Closed` means that the business has definitely closed. `Opening Soon` indicates the business is open with an opening date set in the future. `Temporarily closed` means that the business is temporarily closed.

⚠️ To get all businesses with the status open, regardless of whether the opening_date has passed yet or not, submit both the open and opening_soon options in the filter: status=open,opening_soon

zipcode
string

Filter by zipcode

city
string

Filter by city

code
string

Filter by code

modified__gte
timestamp

Filter by modified attribute (modified >= modified_gte)

subscribed_to_rm
string
Enum: "True" "False"

Filter by current subscription to review_management

subscribed_to_pm
string
Enum: "True" "False"

Filter by current subscription to presence_management

subscribed_to_rb
string
Enum: "True" "False"

Filter by current subscription to review_booster

subscribed_to_bm
string
Enum: "True" "False"

Filter by current subscription to messages

completion_rate__gte
timestamp

Filter by completion_rate attribute (completion_rate >= completion_rate__gte)

completion_rate__lte
timestamp

Filter by completion_rate attribute (completion_rate <= completion_rate__lte)

completion_rate
enum
Enum: "low" "mid" "high"
Example: completion_rate=low,mid

Filter by completion_rate attribute. You can separate the values by a comma, as done in the example.

has_promo
string
Deprecated
Enum: "True" "False"

Retrieve only businesses having promotional offers

connected_to_gmb_location
string
Enum: "True" "False"

Filter by current link to a Google location

connected_to_facebook_location
string
Enum: "True" "False"

Filter by current link to a Facebook location

Responses

Response samples

Content type
application/json
{
  • "average_completion_rate": 72,
  • "counts": {
    }
}

Statistics for your connected businesses

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

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "linked_to_gmb_count": 0,
  • "linked_to_facebook_count": 0,
  • "linked_to_tripadvisor_count": 0
}

Create business

This API allows the creation of a new business in the context of your organisation.

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

The name of the business (POI) as it will appear on the publishing platforms

org_id
integer (BusinessOrgId)

The organisation unique identifier at Partoo. During onboarding, Partoo creates an organisation where all your businesses will be aggregated

groups
array<integer> (groups)

List of Group ID of the business.

Groups the business belongs to.

See the Groups and Sections description

country
required
string (BusinessCountry)

Business country - In the ISO 3166 alpha2 code format (i.e. use “FR” for France instead of "fr")

zipcode
string (BusinessZipcode)

Zipcode (or postal code) for the business address. Can be empty if the business' country does not require one.

city
required
string (BusinessCity)

The city where the business is located

region
string (BusinessRegion)

The region where the business is located. Can be empty, it is only useful for some countries like Italy or Spain among others.

categories
required
Array of arrays (BusinessCategories)

A list of category ids mapped to the business. At least one category needs to be provided. For more information see Categories section

code
string (BusinessCode)

The unique store code of the business. If not provided, it will be automatically generated

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

Defines the current status of the business. open indicates the business is up and running. closed means that the business has definitely closed. temporarily_closed means that the business is temporarily closed, it is advised when your business is closed for more than one week, otherwise use the specific_hours

opening_date
string <YYYY-MM-DD> (BusinessOpeningDate)

The opening_date represents the date when a business was opened. The format of the date must be in ISO 8601 format (YYYY-MM-DD). ⚠️ The date must be in the past or no more than one year in the future from the current date (Google API requirement).

address_full
string (AddressFull)

Full address of the business.

For example : 130 Rue du Mont-Cenis.

address2
string (Address2)

Complement of address. Any additional information that could help better find the business location

lat
number <double> (BusinessLatitude)

Latitude. Decimals are separated by a dot and not by a comma.

long
number <double> (BusinessLongitude)

Longitude. Decimals are separated by a dot and not by a comma.

website_url
string <uri> (BusinessWebsite)

The business own website url or the main url of the company.

facebook_url
string <uri> (BusinessFacebookPage)

Business Facebook page url

twitter_url
string <uri> (BusinessTwitter)

Business twitter page url

description_short
string (BusinessShortDescription)

A short description of the business. It needs to be in the language of the country where the business is located. For example, if the business is located in Madrid, then the description needs to be in Spanish.

⚠️It is limited to 200 characters

description_long
string (BusinessLongDescription)

A more detailed description of the business. It needs to be in the language of the country where the business is located. For example, if the business is located in London, then the description needs to be in English.

⚠️It is limited to 750 characters

object (OpenHours)

The opening hours of the business (in its timezone).

Opening hours are specified per weekday. This is done by supplying an object mapping weekdays ("monday", "tuesday", etc.) to a list of of strings. These strings in turn represent time slots during which the business is open.

For example, the following value would set the opening hours to between 08:00-15:00 in the afternoon and 18:00-23:00 in the evening on Mondays:

{"monday": ["08:00-15:00", "18:00-23:00"]}

To indicate that a business is open 24 hours for a specific weekday, use the value ["00:00-23:59"].

❗ This field is not mandatory, but if not provided then the business will not be pushed on some platforms (example: Google). If provided, then a schedule needs to be sent for each day in particular

object (SpecificHours)

Exceptional opening or closing times for the business (in its timezone).

All exceptional days of the year, including temporarily closed, can be specified beforehand or on the go. For example:

  • Beforehand: bank holidays (like Christmas or Labor Day)
  • Unpredicted: COVID-19 exceptional situation

Specific hours are defined by two values:

  • open, containing a list of days with exceptional opening hours
  • close, containing a list of days where the business is exceptionally closed all day.

These values in turn, contain:

  • starts_at indicating the first date for which the exceptional hours are valid
  • ends_at indicating the last date (inclusive) for which the exceptional hours are valid
  • open_hours (only used for days with exceptional opening hours) indicating the actual time slots for the given period, following the same pattern as the time slots in open_hours
required
Array of objects (BusinessContactsCreate)

Specify how the clients can reach the persons in charge of the business in case they have questions.

object (Photos)

Business photos

Each business can have one or more photos associated

national_identification_number
string (BusinessNationalIdentificationNumber)

The National Identification Number of the business

It describes a unique number for which the business is registered in a specific country. For example, in France, it's SIRET code or for Ireland it's the CRO

object (CustomFields.Update)

Custom Fields set for this Business

They represent configurable fields that can be defined in addition to the normal business fields proposed by Partoo. They are unique to the organisation and should suit your company needs.

Responses

Request samples

Content type
application/json
{
  • "name": "Corner shop",
  • "org_id": 42,
  • "groups": [
    ],
  • "country": "FR",
  • "zipcode": "75019",
  • "city": "Paris",
  • "region": "Ile-de-France",
  • "categories": [
    ],
  • "code": "CS-75019",
  • "status": "open",
  • "opening_date": "2025-01-01",
  • "address_full": "12 bis rue du coquelicot",
  • "address2": "string",
  • "lat": -3.585993,
  • "long": 47.870341,
  • "website_url": "https://www.corner-shop.co/",
  • "facebook_url": "https://www.facebook.com/the-corner-shop",
  • "twitter_url": "https://www.twitter.com/the-corner-shop",
  • "description_short": "lorem ipsum",
  • "description_long": "lorem ipsum dolor sit amet",
  • "open_hours": {
    },
  • "specific_hours": {
    },
  • "contacts": [
    ],
  • "photos": {},
  • "national_identification_number": "string",
  • "custom_fields": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "id": "5409c35a97bbc544d8e26737"
}

Business information

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

Authorizations:
ApiKeyAuth
path Parameters
business_id
required
string

Business id

Responses

Response samples

Content type
application/json
{
  • "id": "5409c35a97bbc544d8e26737",
  • "created": 1409925979.5,
  • "modified": 1561335111.681374,
  • "code": "CS-75019",
  • "status": "open",
  • "opening_date": "2025-01-01",
  • "org_id": 42,
  • "group_id": 23,
  • "groups": [
    ],
  • "name": "Corner shop",
  • "address": "string",
  • "address_full": "12 bis rue du coquelicot",
  • "address2": "string",
  • "city": "Paris",
  • "zipcode": "75019",
  • "region": "Ile-de-France",
  • "country": "FR",
  • "default_lang": "fr",
  • "categories": [
    ],
  • "time_slot_reference": [
    ],
  • "open_hours": {
    },
  • "specific_hours": {
    },
  • "description_short": "lorem ipsum",
  • "description_long": "lorem ipsum dolor sit amet",
  • "website_url": "https://www.corner-shop.co/",
  • "facebook_url": "https://www.facebook.com/the-corner-shop",
  • "twitter_url": "https://www.twitter.com/the-corner-shop",
  • "google_location_id": "string",
  • "facebook_page_id": "string",
  • "national_identification_number": "string",
  • "logo_url": "http://example.com",
  • "contacts": [
    ],
  • "photos": {},
  • "lat": -3.585993,
  • "long": 47.870341,
  • "subscriptions": {
    },
  • "custom_fields": [
    ],
  • "completion_rate": 77,
  • "promos": []
}

Update business

This endpoint lets you access to the information of a business. You need to have WRITE access on this business. Only indicated values are taken into account (it works like a PATCH). You cannot push fields disabled for your org.

Authorizations:
ApiKeyAuth
path Parameters
business_id
required
string

Business id

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

The name of the business (POI) as it will appear on the publishing platforms

org_id
integer (BusinessOrgId)

The organisation unique identifier at Partoo. During onboarding, Partoo creates an organisation where all your businesses will be aggregated

groups
array<integer> (groups)

List of Group ID of the business.

Groups the business belongs to.

See the Groups and Sections description

country
string (BusinessCountry)

Business country - In the ISO 3166 alpha2 code format (i.e. use “FR” for France instead of "fr")

zipcode
string (BusinessZipcode)

Zipcode (or postal code) for the business address. Can be empty if the business' country does not require one.

city
string (BusinessCity)

The city where the business is located

region
string (BusinessRegion)

The region where the business is located. Can be empty, it is only useful for some countries like Italy or Spain among others.

categories
Array of arrays (BusinessCategories)

A list of category ids mapped to the business. At least one category needs to be provided. For more information see Categories section

code
string (BusinessCode)

The unique store code of the business. If not provided, it will be automatically generated

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

Defines the current status of the business. open indicates the business is up and running. closed means that the business has definitely closed. temporarily_closed means that the business is temporarily closed, it is advised when your business is closed for more than one week, otherwise use the specific_hours

opening_date
string <YYYY-MM-DD> (BusinessOpeningDate)

The opening_date represents the date when a business was opened. The format of the date must be in ISO 8601 format (YYYY-MM-DD). ⚠️ The date must be in the past or no more than one year in the future from the current date (Google API requirement).

address2
string

Row address string

address_full
string (AddressFull)

Full address of the business.

For example : 130 Rue du Mont-Cenis.

lat
number <double> (BusinessLatitude)

Latitude. Decimals are separated by a dot and not by a comma.

long
number <double> (BusinessLongitude)

Longitude. Decimals are separated by a dot and not by a comma.

website_url
string <uri> (BusinessWebsite)

The business own website url or the main url of the company.

facebook_url
string <uri> (BusinessFacebookPage)

Business Facebook page url

twitter_url
string <uri> (BusinessTwitter)

Business twitter page url

description_short
string (BusinessShortDescription)

A short description of the business. It needs to be in the language of the country where the business is located. For example, if the business is located in Madrid, then the description needs to be in Spanish.

⚠️It is limited to 200 characters

description_long
string (BusinessLongDescription)

A more detailed description of the business. It needs to be in the language of the country where the business is located. For example, if the business is located in London, then the description needs to be in English.

⚠️It is limited to 750 characters

object (OpenHours)

The opening hours of the business (in its timezone).

Opening hours are specified per weekday. This is done by supplying an object mapping weekdays ("monday", "tuesday", etc.) to a list of of strings. These strings in turn represent time slots during which the business is open.

For example, the following value would set the opening hours to between 08:00-15:00 in the afternoon and 18:00-23:00 in the evening on Mondays:

{"monday": ["08:00-15:00", "18:00-23:00"]}

To indicate that a business is open 24 hours for a specific weekday, use the value ["00:00-23:59"].

❗ This field is not mandatory, but if not provided then the business will not be pushed on some platforms (example: Google). If provided, then a schedule needs to be sent for each day in particular

object (SpecificHours)

Exceptional opening or closing times for the business (in its timezone).

All exceptional days of the year, including temporarily closed, can be specified beforehand or on the go. For example:

  • Beforehand: bank holidays (like Christmas or Labor Day)
  • Unpredicted: COVID-19 exceptional situation

Specific hours are defined by two values:

  • open, containing a list of days with exceptional opening hours
  • close, containing a list of days where the business is exceptionally closed all day.

These values in turn, contain:

  • starts_at indicating the first date for which the exceptional hours are valid
  • ends_at indicating the last date (inclusive) for which the exceptional hours are valid
  • open_hours (only used for days with exceptional opening hours) indicating the actual time slots for the given period, following the same pattern as the time slots in open_hours
Array of objects (BusinessContacts)

Specify how the clients can reach the persons in charge of the business in case they have questions.

object (Photos)

Business photos

Each business can have one or more photos associated

national_identification_number
string (BusinessNationalIdentificationNumber)

The National Identification Number of the business

It describes a unique number for which the business is registered in a specific country. For example, in France, it's SIRET code or for Ireland it's the CRO

object (CustomFields.Update)

Custom Fields set for this Business

They represent configurable fields that can be defined in addition to the normal business fields proposed by Partoo. They are unique to the organisation and should suit your company needs.

Responses

Request samples

Content type
application/json
{
  • "name": "Corner shop",
  • "org_id": 42,
  • "groups": [
    ],
  • "country": "FR",
  • "zipcode": "75019",
  • "city": "Paris",
  • "region": "Ile-de-France",
  • "categories": [
    ],
  • "code": "CS-75019",
  • "status": "open",
  • "opening_date": "2025-01-01",
  • "address2": "string",
  • "address_full": "12 bis rue du coquelicot",
  • "lat": -3.585993,
  • "long": 47.870341,
  • "website_url": "https://www.corner-shop.co/",
  • "facebook_url": "https://www.facebook.com/the-corner-shop",
  • "twitter_url": "https://www.twitter.com/the-corner-shop",
  • "description_short": "lorem ipsum",
  • "description_long": "lorem ipsum dolor sit amet",
  • "open_hours": {
    },
  • "specific_hours": {
    },
  • "contacts": [
    ],
  • "photos": {},
  • "national_identification_number": "string",
  • "custom_fields": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "id": "5409c35a97bbc544d8e26737"
}

Delete business

This endpoint lets you delete a business. You need to have WRITEaccess on this business.

Authorizations:
ApiKeyAuth
path Parameters
business_id
required
string

Business id

Responses

Response samples

Content type
application/json
{
  • "id": "5409c35a97bbc544d8e26737",
  • "status": "success"
}

Subscriptions for your business

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

Authorizations:
ApiKeyAuth
path Parameters
business_id
required
string

Business id

Responses

Response samples

Content type
application/json
{
  • "presence_management": {
    },
  • "review_management": {
    },
  • "review_booster": {
    },
  • "messages": {
    }
}

Subscribe a business

This endpoint lets you subscribe a business to one or several Partoo products. You need to have WRITE access on the business you want to subscribe. You need to have PROVIDER to be able to perform this action.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
subscription_date
number

Timestamp representing the date on which the subscription will start

products
Array of strings (Product)
Items Enum: "presence_management" "review_booster" "review_management" "messages"

List of products

plan
string

Any string that define your offer

Responses

Request samples

Content type
application/json
{
  • "subscription_date": 1540628702,
  • "products": [
    ],
  • "plan": "string"
}

Response samples

Content type
application/json
{
  • "presence_management": {
    },
  • "review_management": {
    },
  • "review_booster": {
    },
  • "messages": {
    }
}

Unsubscribe a business

This endpoint lets you unsubscribe a business from one or several Partoo products. You need to have WRITE access on the business you want to subscribe. You need to have PROVIDER to be able to perform this action.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
canceling_date
number

Timestamp representing the date on which the subscription will stop to be valid

products
Array of strings (Product)
Items Enum: "presence_management" "review_booster" "review_management" "messages"

List of products

Responses

Request samples

Content type
application/json
{
  • "canceling_date": 1540628702,
  • "products": [
    ]
}

Response samples

Content type
application/json
{
  • "presence_management": {
    },
  • "review_management": {
    },
  • "review_booster": {
    },
  • "messages": {
    }
}

Additional data for your business

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

Authorizations:
ApiKeyAuth
path Parameters
business_id
required
string

Business id

Responses

Response samples

Content type
application/json
{
  • "additionnal_data_1": "Some data",
  • "additionnal_data_2": 3.1415
}

Set additional data for your business

This endpoint lets you set additional data on a business. You need to have WRITE access on this business. Additional is a flat object with at most 10 keys.

Authorizations:
ApiKeyAuth
path Parameters
business_id
required
string

Business id

Request Body schema: application/json
additionnal_data_1
string
additionnal_data_2
number

Responses

Request samples

Content type
application/json
{
  • "additionnal_data_1": "Some data",
  • "additionnal_data_2": 3.1415
}

Response samples

Content type
application/json
{
  • "id": "5409c35a97bbc544d8e26737",
  • "status": "success"
}

Google attributes for your business

This endpoint allows you to view the Google attributes set for your business.

Authorizations:
ApiKeyAuth
path Parameters
business_id
required
string

Business id

category_name
string
Example: gcid:restaurant

Category for which availabe attributes will be fetched.

country
required
string
Example: FR

Country for which available attributes will be fetched - use ISO 3166 alpha2 code ("FR", "EN", "IT").

Responses

Response samples

Content type
application/json
{
  • "attributes": [
    ]
}

Set Google attributes for your business

This endpoint allows you to set Google attributes for your business.

Authorizations:
ApiKeyAuth
path Parameters
business_id
required
string

Business id

Request Body schema: application/json
Array of Attributes.Field.BOOL (object) or Attributes.Field.ENUM (object) or Attributes.Field.REPEATABLE_ENUM (object) or Attributes.Field.URL (object) or Attributes.Field.REPEATABLE_URL (object) (PostAttributes.Array)

List of Business Attributes

Responses

Request samples

Content type
application/json
{
  • "attributes": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success"
}

More hours for your business

This endpoint allows you to view the More Hours set for your business.

Authorizations:
ApiKeyAuth
path Parameters
category
string
Example: gcid:restaurant

If supplied, will only return more hours that are available for the specified business category. If not supplied, the business' main category will be used.

country
string
Example: FR

If supplied, will only return more hours that are available in the specified country. - use ISO 3166 alpha2 code ("FR", "EN", "IT"). If not supplied, the country from the business' address will be used.

Responses

Response samples

Content type
application/json
{
  • "more_hours": [
    ]
}

Set more hours for your business

This endpoint allows you to set the More Hours for your business.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
Array of objects

Array containing the more hours values to update. Grouped by More Hour ID. Only More Hour IDs included in the body will be updated.

Responses

Request samples

Content type
application/json
{
  • "more_hours": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "id": "545f7bf982efa41a496379d2"
}

Google Services for your business

This endpoint allows you to view the Google Services set for your business.

Authorizations:
ApiKeyAuth
path Parameters
business_id
required
string

Business id

Responses

Response samples

Content type
application/json
{
  • "services": [
    ]
}

Delete Google Services for your business

This endpoint allows you to delete the Google Services set for your business.

Authorizations:
ApiKeyAuth
path Parameters
business_id
required
string

Business id

Request Body schema: application/json
service_id
required
integer (ServiceId)

Id of the service (For creation you can get this id by calling get services suggestions endpoint)

Responses

Request samples

Content type
application/json
{
  • "service_id": 1
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Set Google Services for your business

This endpoint allows you to set or update Google Services for your business. When you set a service of type STRUCTURED_SERVICE_ITEM for a category, every category that have this service available will also have it set for them.

Authorizations:
ApiKeyAuth
path Parameters
business_id
required
string

Business id

Request Body schema: application/json
service_id
required
integer (ServiceId)

Id of the service (For creation you can get this id by calling get services suggestions endpoint)

price
float (ServicePrice)

Price of the service.

description
string (ServiceDescription) <= 300 characters

Description of the service.

Responses

Request samples

Content type
application/json
{
  • "service_id": 1,
  • "price": 12.5,
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "services": [
    ]
}

Set custom Google Services for your business

This endpoint allows you to set or update custom Google Services for your business.

Authorizations:
ApiKeyAuth
path Parameters
business_id
required
string

Business id

Request Body schema: application/json
Any of
category_gmb_id
string
Deprecated

Google Id of the category. The category must belong to your business.

category_gmb_name
required
string

Google name of the category. The category must belong to your business.

name
required
string

Name of the service.

price
float

Price of the service.

description
string <= 300 characters

Description of the service.

Responses

Request samples

Content type
application/json
Example
{
  • "category_gmb_id": "gcid:climbing_gym",
  • "category_gmb_name": "gcid:climbing_gym",
  • "name": "Random Name",
  • "price": 25.35,
  • "description": "This is our custom service"
}

Response samples

Content type
application/json
{
  • "services": [
    ]
}

Google Food Menus for your business

This endpoint allows you to view the Google Food Menus set for your business.

Authorizations:
ApiKeyAuth
path Parameters
business_id
required
string

Business id

Responses

Response samples

Content type
application/json
{}

Delete Google Food Menus for your business

This endpoint allows you to delete the Google Food Menus for your business.

Authorizations:
ApiKeyAuth
path Parameters
business_id
required
string

Business id

Responses

Response samples

Content type
application/json
{
  • "status": "success"
}

Set Google Food Menus for your business

This endpoint allows you to set or update Google Food Menus for your business.

Authorizations:
ApiKeyAuth
path Parameters
business_id
required
string

Business id

Request Body schema: application/json
Array of objects (FoodMenuSection)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Business urls on publishers Deprecated

This endpoint lets you access to the urls corresponding to the business on publisher websites. You need to have READ access on this business.

Authorizations:
ApiKeyAuth
path Parameters
business_id
required
string

Business id

Responses

Response samples

Content type
application/json
{}

Business integration data Deprecated

This endpoint lets you access to the data summarizing the integration state of a business on publishers. You need to have READ access on this business.

Authorizations:
ApiKeyAuth
path Parameters
business_id
required
string

Business id

Responses

Response samples

Content type
application/json
{
  • "apple": {
    },
  • "le118000": {
    },
  • "les_horaires": {
    },
  • "wemap": {
    },
  • "here": {
    },
  • "google_my_business": {
    },
  • "hoodspot": {
    },
  • "foursquare": {
    },
  • "facebook": {
    },
  • "justacote": {
    },
  • "navmii": {
    },
  • "bing_fr": {
    }
}

Business Fields

These endpoints give you the list of all the fields that are available for the business / organization / provider, grouped by section.

A section corresponds to the tabs in the Business Edit view of Partoo UI. Examples: Coordinates, Description, Custom Fields...

Each section contains an array of fields that are displayed within it. Examples: Name, Country, Email...

For each field, these endpoints give you the permissions for each fields, depending on your role:

  • enabled Your right to write on a field, given by roles less restricitves than yours.
  • enabled_for_subroles The right to write on a field you give to roles more restrictives than yours.

    For example:

  • If the user is ORG_ADMIN, enabled_for_subroles describes the permissions of the field for all the GROUP_MANAGER and BUSINESS_MANAGER of the given organization.
  • If the user is PROVIDER, enabled_for_subroles describes the permissions of the field for all the ORG_ADMIN, GROUP_MANAGER and BUSINESS_MANAGER of the given provider.

    For each custom_fields, these endpoints also give you their metadata:

  • Type, id and order for all of them
  • Constraints such as minimum and maximum for a number or list of values for a select.

    See the response schema below for more details about each type metadata.

    • Business fields configuration for a business

    This endpoint gives you the list of all the fields that are available for a given Business.

    It also tells you, for each field, if you have the permission to edit it or not, depending of the permission configured by your ORG_ADMIN and your PROVIDER.

    Authorizations:
    ApiKeyAuth
    path Parameters
    business_id
    required
    string

    Business id

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ]

    Business fields configuration for an organization

    This endpoint gives you the list of all the fields that are available for a given Organization.

    Also tells you, for each field:

  • If you have the permission to edit it or not, depending of the permission configured by PROVIDER.
  • If you gave the persission to edit it or not for the BUSINESS_MANAGER and GROUP_MANAGER who have access to the businesses of the organization.

    Only User roles ORG_ADMIN or PROVIDER can access this information.

    • Authorizations:
    ApiKeyAuth
    path Parameters
    org_id
    required
    integer

    Organisation id

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ]

    Categories

    Categories describe your business and has a huge impact on its discoverability on directories. For each business, you will need to pass at least one category id (example: "gcid:restaurant") and up to 10. Please note that the order you pass to business.categories array is important: the first category id should correspond to the most relevant category for your business.

    You can find below all available operations that will let you get more information about categories you can use on Partoo.

    List Partoo categories

    This endpoint lets you read and filter through Partoo categories.

    Authorizations:
    ApiKeyAuth
    query Parameters
    country
    string
    Example: country=FR

    Filters categories available for businesses in given country.

    If no country is given, then the endpoint returns the list of all existing available categories.

    Use country ISO 3166 alpha2 code.

    lang
    string (Lang)
    Enum: "fr" "en" "es" "it" "pt-br" "de" "ar"
    Example: lang=fr

    Language to get the category name. If not given, the user's language is used.

    state
    string
    Enum: "OK" "DEPRECATED"
    block_push_long_description_on_gmb
    boolean

    Filter on block_push_long_description_on_gmb param (boolean indicating if the business long description can be pushed to Google when the business belongs to this category)

    search_query
    string

    Fuzzy search on gmb_id and names translations

    order_by
    string
    Enum: "gmb_id" "-gmb_id"

    Order results by colum. Add "-" before for ordering by descending order.

    live__isnull
    any

    Filter on live_id parameter value

    True: Recover categories which live_id is null

    False: Recover categories which live_id is not null

    Null: Do not filter on live_id

    page
    integer
    Default: 0

    Page number. 30 results per page

    per_page
    integer [ 1 .. 100 ]
    Default: 30

    Number of items to return per page. Currently limited to 100.

    with_names
    boolean
    Default: false

    Returns an object representing the list of translations in the available languages for the requested category. See example on the right.

    If with_names is true, the translations will appear in the field names

    with_countries
    boolean
    Default: false

    Returns an array of strings representing the list of country codes in which the requested category is available.

    If with_countries is true, the country list will appear in the field countries

    Responses

    Response samples

    Content type
    application/json
    Example
    [
    • {
      }
    ]

    Category information

    This endpoint lets you retrieve the data of a specific category.

    Authorizations:
    ApiKeyAuth
    path Parameters
    required
    integer or string (CategoryId)
    Example: 5706 or gcid:bank

    Category id or Google's category id

    query Parameters
    lang
    string (Lang)
    Enum: "fr" "en" "es" "it" "pt-br" "de" "ar"
    Example: lang=fr

    Language to get the category name. If not given, the user's language is used.

    return_live
    boolean
    Default: false

    Return the corresponding live category instead of the requested category

    with_names
    boolean
    Default: false

    Returns an object representing the list of translations in the available languages for the requested category. See example on the right.

    If with_names is true, the translations will appear in the field names

    with_countries
    boolean
    Default: false

    Returns an array of strings representing the list of country codes in which the requested category is available.

    If with_countries is true, the country list will appear in the field countries

    Responses

    Response samples

    Content type
    application/json
    Example
    [
    • {
      }
    ]

    Suggested additional categories

    This endpoint lets you retrieve Partoo's suggestions for additional categories, based on a given category.

    Authorizations:
    ApiKeyAuth
    path Parameters
    required
    integer or string (CategoryId)
    Example: 5706 or gcid:bank

    Category id or Google's category id

    query Parameters
    lang
    string (Lang)
    Enum: "fr" "en" "es" "it" "pt-br" "de" "ar"
    Example: lang=fr

    Language to get the category name. If not given, the user's language is used.

    Responses

    Response samples

    Content type
    application/json
    {
    • "categories": [
      ]
    }

    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:
    ApiKeyAuth
    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

    Request samples

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

    Response samples

    Content type
    application/json
    {
    • "token": "\\xaf3e8951c1f4c42f9cc53116b3fc855bd44bce01cf27604b",
    • "expiration_date": "2019-08-01T19:15:54.256000+02:00"
    }

    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:
    ApiKeyAuth
    Request Body schema: application/json
    user_id
    required
    string (UserId)

    User id

    token
    string

    Token to revoke

    Responses

    Request samples

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

    Response samples

    Content type
    application/json
    { }

    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:
    ApiKeyAuth
    query Parameters
    user_id
    required
    string (UserId)
    Example: user_id=5309c3a237bbc544d8e26737

    User id

    token
    required
    string
    Example: token=\xaf3e8951c1f4c42f9cc53116b3fc855bd44bce01cf27604b

    User connection token

    Responses

    Response samples

    Content type
    application/json
    {
    • "token": "\\xaf3e8951c1f4c42f9cc53116b3fc855bd44bce01cf27604b",
    • "expiration_date": "2019-08-02T19:15:54.256000+02:00",
    • "generated_by": "5309c3a237bbc544d8e26737",
    • "creation_date": "2019-08-01T19:15:54.256000+02:00",
    • "consumption_date": "2019-08-01T23:15:54.256000+02:00",
    • "status": "consumed"
    }

    Custom Fields

    All operations available on Custom Fields metadata : creation, update and deletion of custom fields.

    ⚠️ What are Custom fields ?

    Custom Fields allow Enterprise Administrators to add custom data fields to businesses in Partoo / Localoo under different formats (List, Text, Number…) in order to create a central datahub for local information. These fields can be used to:

  • Automatically feed other tools (Store locator, website, CRM, Chatbot...) from Partoo / Localoo.
  • Allow local users to fill custom fields in order to transmit data from local to central.

    Once created, Custom Fields values can be updated like any other business field.

    To handle custom fields values for businesses, see business endpoints.

    To recover the list of custom fields available for a business see GET business fields endpoint.

    • Create custom fields

    This endpoint enables you to create custom fields for your organization as an ORG_ADMIN

    Authorizations:
    ApiKeyAuth
    Request Body schema: application/json
    Any of
    name
    string (CustomFieldName) [ 1 .. 50 ] characters

    The name of the custom field

    type
    string (CustomFieldTypeBool) non-empty

    BOOLEAN

    order
    integer (CustomFieldOrder)
    Default: 10

    Describes where the custom field is displayed on the Business Edit view of the Partoo App

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "name": "Click and collect",
    • "type": "BOOLEAN",
    • "order": 30
    }

    Response samples

    Content type
    application/json
    {
    • "id": 42
    }

    Update custom field

    This endpoint enables an ORG_ADMIN to update a specific custom field of his organization by specifying its id.

    Name and constraints can be updated. The type of a custom field cannot be modified.

    Authorizations:
    ApiKeyAuth
    path Parameters
    custom_field_id
    required
    integer (CustomFieldId)
    Example: 42

    Id of the custom field

    Request Body schema: application/json
    Any of
    name
    string (CustomFieldName) [ 1 .. 50 ] characters

    The name of the custom field

    type
    string (CustomFieldTypeBool) non-empty

    BOOLEAN

    forced_update
    boolean (CustomFieldForcedUpdate)
    Default: false

    The deletion of a custom field or the update of its metadata can have impacts on custom fields which are already set for businesses.

    • If forced_update is set to false, updates/deletions will be performed only if they are non destructive. If some businesses would be impacted by the update/deletion, an exception will be returned
    • If forced_update is set to true, destructive modification will be performed and businesses values will be deleted accordingly.

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "name": "Click and collect",
    • "type": "BOOLEAN",
    • "forced_update": false
    }

    Response samples

    Content type
    application/json
    {
    • "id": "success"
    }

    Delete custom field

    This endpoint enables an ORG_ADMIN to delete a specific custom field of his organization by specifying its id.

    Authorizations:
    ApiKeyAuth
    path Parameters
    custom_field_id
    required
    integer (CustomFieldId)
    Example: 42

    Id of the custom field

    Request Body schema: application/json
    forced_update
    boolean (CustomFieldForcedUpdate)
    Default: false

    The deletion of a custom field or the update of its metadata can have impacts on custom fields which are already set for businesses.

    • If forced_update is set to false, updates/deletions will be performed only if they are non destructive. If some businesses would be impacted by the update/deletion, an exception will be returned
    • If forced_update is set to true, destructive modification will be performed and businesses values will be deleted accordingly.

    Responses

    Request samples

    Content type
    application/json
    {
    • "forced_update": false
    }

    Response samples

    Content type
    application/json
    {
    • "id": "success"
    }

    Order custom fields

    This endpoint enables you to reorganize the order of the custom fields of your organization

    Authorizations:
    ApiKeyAuth
    Request Body schema: application/json
    required
    Array of objects (CustomFieldOrders)

    On the Business Edit view of the Partoo App, custom fields will be displayed depending on their order.
    The lowest number will be the first.

    Responses

    Request samples

    Content type
    application/json
    {
    • "orders": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "id": "success"
    }

    Google

    All the operations you can perform on Google.

    List Google Attributes

    Get all Google Attributes available for a Category in a given language.

    ⚠️ What are Google Attributes ?

    Google Attributes are highly visible statements about your business that appear on your Google listing.

    They indicate things like Payment Options, Amenities, Accessibility and Highlights.

    Does a business provide parking? Does it have a fireplace? Can customers pay with a debit card?

    To recover attributes values set for a business, see get attributes business endpoints.

    To handle attributes values for businesses, see set attributes business endpoints.

    This endpoint allows you to view the **Google** attributes available for a given Category.

    Authorizations:
    ApiKeyAuth
    path Parameters
    category_name
    required
    string
    Example: gcid:restaurant

    Category for which availabe attributes will be fetched.

    country
    required
    string
    Example: FR

    Country for which available attributes will be fetched - use ISO 3166 alpha2 code ("FR", "EN", "IT").

    lang
    string
    Enum: "fr" "es" "it" "en" "de" "pt" "pt-BR"

    Language in which the attributes name and groups name will be translated.

    If language is not specified, by default we take the language of the user.

    Responses

    Response samples

    Content type
    application/json
    {
    • "groups": [
      ]
    }

    List Google more hours

    ⚠️ What are Google More Hours ?

    More Hours is a feature in Google that allows the business owner to display hours for specific services available.

    Examples of such services include opening hours for the kitchen, for breakfast, for happy hour, etc.

    Notice that the available More Hour IDs vary between both business categories and countries. For example, a restaurant will have different More Hour IDs available than a bank, and a restaurant in France will have different IDs available than a restaurant in the USA.

    To recover More Hours set for a business, see Get More Hours for your Business endpoints.

    To handle More Hours for businesses, see Update More Hours for your Business endpoints.

    This endpoint allows you to get all the different **More Hour IDs** available for a given business category, including their translated names for the given language.

    Authorizations:
    ApiKeyAuth
    path Parameters
    category
    required
    string
    Example: gcid:restaurant

    Category for which availabe More Hour IDs will be fetched.

    country
    required
    string
    Example: FR

    Country for which available More Hour IDs will be fetched - use ISO 3166 alpha2 code ("FR", "EN", "IT").

    lang
    string
    Enum: "fr" "es" "it" "en" "de" "pt" "pt-BR"

    Language in which the More Hours names will be translated.

    If language is not specified, by default we take the language of the user.

    Responses

    Response samples

    Content type
    application/json
    {
    • "more_hours": [
      ]
    }

    List Google Services

    Get all Google Services available for your business categories.

    ⚠️ What are Google Services ?

    Google Services are highly visible statements about your business that appear on your Google listing.

    They indicate the different services available for your business, to which you can also add a price and a description.

    For example, the category gcid:bakery has several suggested services available, such as catering or delivery.

    Not satisfy with those ? You can add your very own custom services and link them to the category of your business of your choice !

    To recover services values set for a business, see get services business endpoints.

    To handle services values for businesses, see set structured services business endpoints.

    To handle custom services values for businesses, see set free form services business endpoints.

    This endpoint allows you to view the Google Services available for your business.

    The services available depends on the categories of the business not only the main one.

    Authorizations:
    ApiKeyAuth
    query Parameters
    business__in
    Array of strings (BusinessId)
    Example: business__in=5409c35a97bbc544d8e26737

    Filter by business ids

    Responses

    Response samples

    Content type
    application/json
    {
    • "services_suggestions": [
      ]
    }

    Details on a specific Google Location

    Returns a Google location object that corresponds to the given google_location_id. The google_location_id is a unique identifier on Partoo for each location. This endpoint requires authentication, and only authorized users with the appropriate permissions can access it.

    Authorizations:
    ApiKeyAuth
    path Parameters
    google_location_id
    required
    string

    Google location unique id on Partoo

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "6047dac0604f33da03018004",
    • "location_name": "Annie - HQ",
    • "store_code": "annie-hq",
    • "region_code": "FR",
    • "postal_code": "75018",
    • "address_details": "130 rue mont cenis",
    • "locality": "Paris",
    • "place_id": "ChIJ3Qu-HpFt5kcRNHUedqwIzQY",
    • "google_verifications": {
      },
    • "phone_numbers": "0675181818"
    }

    Fetch Google Location Verification Options

    This endpoint retrieves verification options for a specific Google location identified by google_location_id. It requires authentication and authorization to access. The user must have at least the role of a BUSINESS_MANAGER to use this endpoint.

    Note that the response can return an empty options list, this can mean two things:

    • There are really no verification options available for this location.
    • Video verification is possible but not implemented through the API. In this case, you should ask the user to manually verify.
    Authorizations:
    ApiKeyAuth
    path Parameters
    google_location_id
    required
    string

    Google location unique id on Partoo

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "options": [
      ],
    • "message": null
    }

    Start Google Location Verification Process

    This endpoint initiates the verification process for a specific Google location identified by google_location_id. It requires authentication and authorization to access. The user must have at least the role of a BUSINESS_MANAGER to use this endpoint.

    The endpoint ensures that the chosen verification method has all the necessary information for the specific method chosen. If any required information is missing, it raises an error with the associated error message.

    Authorizations:
    ApiKeyAuth
    path Parameters
    google_location_id
    required
    string

    Google location unique id on Partoo

    Request Body schema: application/json
    method
    string
    Enum: "SMS" "PHONE_CALL" "EMAIL" "ADDRESS"
    phone_number
    string

    REQUIRED for SMS and PHONE_CALL methods. The phone number to which the code will be send.

    email
    string

    REQUIRED for EMAIL method. The email address to which the code will be send.

    full_name
    string

    REQUIRED for ADDRESS method. The full name to which the postcard will be send.

    Responses

    Request samples

    Content type
    application/json
    {
    • "method": "SMS",
    • "phone_number": "+33187662490",
    • "email": "email.api@partoo.fr",
    • "full_name": "John Doe"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "message": null
    }

    Complete Google Location Verification Process

    This endpoint completes the Google location verification process identified by google_location_id. It requires authentication and authorization with at least the role of BUSINESS_MANAGER.

    If the verification process is not in the PENDING status, or if the PIN code is invalid, an error response will be returned. If the completion is successful, the verification status of the location will be updated.

    Authorizations:
    ApiKeyAuth
    path Parameters
    google_location_id
    required
    string

    Google location unique id on Partoo

    Request Body schema: application/json
    method
    string
    Enum: "PHONE_CALL" "SMS" "EMAIL" "ADDRESS"
    pin_code
    string

    The PIN code provided by the user during the verification process.

    Responses

    Request samples

    Content type
    application/json
    {
    • "method": "PHONE_CALL",
    • "pin_code": "1234"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "message": null
    }

    Groups [OLD]

    ⚠️ This old group system is now deprecated and will be removed in the future. Please use the New Group System instead.

    Groups represent a collection of businesses managed by one or multiple group managers. Their purpose is to simulate the clients business hierarchy/organisation and ease the visibility over them. An organisation can have multiple groups and each group can have multiple subgroups.

    A subgroup can have only businesses and no other nested subgroups!

    List groups Deprecated

    This endpoint returns all the information about the groups that the user has access to.

    Authorizations:
    ApiKeyAuth
    query Parameters
    name__contains
    string
    Example: name__contains=bakery

    Perform a fuzzy search on the group names

    page
    integer
    Default: 1

    Page number. Starts at 1. 100 results per page.

    Responses

    Response samples

    Content type
    application/json
    {
    • "page": 1,
    • "max_page": 10,
    • "count": 287,
    • "groups": [
      ]
    }

    Create group Deprecated

    This endpoint enables the creation of a group by giving a name. WRITE access on the organisation is needed in order to create a group.

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

    Group name

    parent_id
    integer / null (GroupParentId)

    Group parent Id. If not null, it means it's a subgroup.

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "ComfyZone Paris",
    • "parent_id": null
    }

    Response samples

    Content type
    application/json
    {
    • "id": 23,
    • "org_id": 42,
    • "parent_id": null,
    • "created": "2019-08-01T19:15:54.256000+02:00",
    • "updated": "2019-09-01T15:12:35.256000+02:00",
    • "name": "ComfyZone Paris",
    • "provider": "partoo",
    • "subgroup": [
      ]
    }

    Group information Deprecated

    This endpoint returns all the information about a specific group.

    Authorizations:
    ApiKeyAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": 23,
    • "org_id": 42,
    • "parent_id": null,
    • "created": "2019-08-01T19:15:54.256000+02:00",
    • "updated": "2019-09-01T15:12:35.256000+02:00",
    • "name": "ComfyZone Paris",
    • "provider": "partoo",
    • "subgroup": [
      ]
    }

    Update group Deprecated

    This endpoint enables the modification of a group. WRITE access on the organisation is needed in order to be able to update a group.

    Authorizations:
    ApiKeyAuth
    Request Body schema: application/json
    name
    string (GroupName)

    Group name

    parent_id
    integer / null (GroupParentId)

    Group parent Id. If not null, it means it's a subgroup.

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "ComfyZone Paris",
    • "parent_id": null
    }

    Response samples

    Content type
    application/json
    {
    • "id": 23,
    • "org_id": 42,
    • "parent_id": null,
    • "created": "2019-08-01T19:15:54.256000+02:00",
    • "updated": "2019-09-01T15:12:35.256000+02:00",
    • "name": "ComfyZone Paris",
    • "provider": "partoo",
    • "subgroup": [
      ]
    }

    Delete group Deprecated

    This endpoint enables the deletion of a group by giving the group_id. WRITE access on the organisation is needed in order to delete a group. A group manager can not delete a group.

    Authorizations:
    ApiKeyAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": 23,
    • "status": "success"
    }

    List of ids for businesses belonging to a group Deprecated

    This endpoint returns a list of ids of the businesses that belong to a specific group.

    Authorizations:
    ApiKeyAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "ids": [
      ]
    }

    Manage businesses Deprecated

    This endpoint lets you update the list of businesses within a specific group. It replaces the previous list of businesses with a new one. The new list can be directly specified using business__in parameter or built through a set of filters. You need to have WRITE access on the organisation if you want to update the businesses.

    Authorizations:
    ApiKeyAuth
    Request Body schema: application/json
    business__in
    Array of strings (business_ids)

    List of business ids

    business_query
    string (Query)

    Search business by name or address

    business_city
    string (BusinessCity)

    The city where the business is located

    business_org_id
    integer (OrgId)

    Organisation id

    Responses

    Request samples

    Content type
    application/json
    {
    • "business__in": [
      ],
    • "business_query": "Partoo",
    • "business_city": "Paris",
    • "business_org_id": 42
    }

    Response samples

    Content type
    application/json
    {
    • "ids": [
      ]
    }

    Groups and Sections [NEW]

    Introduction

    Our group system has undergone a significant upgrade to offer enhanced flexibility in organizing businesses. Previously, only groups and subgroups were supported, with businesses limited to membership in a single group or subgroup. Users with the BUSINESS_MANAGER role could also only manage businesses from the same group, which was not ideal.

    Main changes with the new Groups system

    • A Business is no longer restricted to only one Group, it can now belong to multiple Groups
    • A user with the BUSINESS_MANAGER can now manage businesses from multiple Groups
    • Subgroups are no longer supported, as you can now set a business in multiple Groups instead
    • To facilitate filtering, groups are now gathered into Sections

    Example of new Groups architecture

    Here, Country /Facade Color / Service are the sections in which groups are organized.

    A business can belong to any combination of these groups, for example:

    • France / Blue
    • Spain / Green / Red / Bakery
    • Italy / Pharmacy

    Filtering

    Groups are used as a filtering system, either to filter businesses by group in our different pages (such as our Analytics pages), or to assign multiple businesses to a user using groups:

    • When selecting different groups from the same section, the system will consider the selection as an "OR" condition. Example: selecting "France" and "Spain" will return all businesses that belong to either "France" or "Spain".
    • When selecting groups from different sections, the system will consider the selection as an "AND" condition. Example: selecting "France" and "Blue" will return all businesses that belong to both "France" and "Blue".

    Group Manager accesses

    Before, with the old group system, a user with the GROUP_MANAGER role could only manage businesses from the same group. Now, with the new group system, a user with the GROUP_MANAGER role can manage businesses using groups combinations.

    A business filtering using groups is what we will call an access. For example, the access "France/Bakery" will return all businesses that belong to the "France" group and the "Bakery" group.

    A GROUP_MANAGER can be assigned to one or multiple accesses, and will be able to manage all businesses that belong to the groups included in one of these accesses.

    Example

    We could have a simple GROUP_MANAGER that can manage all Bakery businesses in France, so we would create an access "France/Bakery" and assign it to this user:

    In the rarer cases where we would need more complex accesses, we could create multiple accesses for the same user. For example, this user can manage:

    • All banks in France
    • All green pharmacies in Italy

    What are the impacts for me ?

    If your organization didn't use the old group system, you don't need to do anything, you can start using the new group system right away, and the old group system will be automatically disabled.

    If your organization was already using the old group system, the new groups system won't be enabled right away, as it would induce breaking changes. You will have 6-9 months to migrate to the new group system, and will be able to switch back and forth between the old and new group systems to do your testing during this period using the groups config endpoint.

    Assigning groups to businesses and accesses to users

    Get organisation status regarding new group system.

    Get information of whether or not an organisation can and/or already has switched to the new group system.
    For more information about the new group system, see the Groups and Sections description.

    Authorizations:
    ApiKeyAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "can_switch_groups_version": true,
    • "switched_to_new_groups": true
    }

    Switch to New Group System

    Update an organisation to use the new group system.
    For more information about the new group system, see the Groups and Sections description.

    Authorizations:
    ApiKeyAuth
    Request Body schema: application/json
    switched_to_new_groups
    required
    bool

    Whether or not to switch the org over to the new group system.

    Responses

    Request samples

    Content type
    application/json
    {
    • "switched_to_new_groups": true
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "org_id": 1
    }

    Create Section

    Create a new section.
    This endpoint endpoint let's you create a new section. Only Group Managers and above can use this endpoint. Business Managers are restricted from accessing this endpoint. For more information about the new group system, see the Groups and Sections description.

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

    Name of the section. Cannot include any of the following characters: ,;/

    org_id
    integer (SectionCreateOrgId)

    ID of the organisation in which to create the section (only available to PROVIDER users)

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "Country",
    • "org_id": 1
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "id": 1
    }

    Get Sections

    Get all the sections for an organization.
    For more information about the new group system, see the Groups and Sections description.

    Authorizations:
    ApiKeyAuth
    Request Body schema: application/json
    page
    any (query_page)

    Page number. 30 results per page

    org_id
    integer (SectionsGetOrgId)

    ID of the organisation of which to get sections from (only available to PROVIDER users)

    Responses

    Request samples

    Content type
    application/json
    {
    • "page": null,
    • "org_id": 1
    }

    Response samples

    Content type
    application/json
    {
    • "page": 1,
    • "count": 6,
    • "max_page": 1,
    • "sections": [
      ]
    }

    Delete Section

    Delete a section.
    This endpoint endpoint let's you delete an existing section. Only Group Managers and above can use this endpoint. Business Managers are restricted from accessing this endpoint. For more information about the new group system, see the Groups and Sections description.

    Authorizations:
    ApiKeyAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "id": 1
    }

    Update Section

    Update the name of a section.
    This endpoint endpoint let's you update an existing section. Only Group Managers and above can use this endpoint. Business Managers are restricted from accessing this endpoint. For more information about the new group system, see the Groups and Sections description.

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

    Name of the section. Cannot include any of the following characters: ,;/

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "Country"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "id": 1
    }

    Get Section by ID

    Get a single section.
    For more information about the new group system, see the Groups and Sections description.

    Authorizations:
    ApiKeyAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": 1,
    • "name": "Country",
    • "groups": [
      ],
    • "can_edit": true,
    • "has_puller": true
    }

    Create Group and set businesses

    Create a new group.
    This endpoint allows Group Managers to create new groups within the system. For more information about the new group system, see the Groups and Sections description.

    ⚠️ You need to precise which businesses are part of the group when creating it using the business__in parameter. If don't precise any business, the group will be created with all the businesses. If you want to create an empty group, you can just put an empty array in the business__in parameter.

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

    Name of the group. Cannot include any of the following characters: ,;/

    business__in
    required
    Array of strings (business_ids)

    List of business ids

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "France",
    • "business__in": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "id": 1
    }

    Update Group and set businesses

    Update a group.
    This endpoint endpoint let's you modify existing group details within the system. Only Group Managers and above can use this endpoint. Business Managers are restricted from accessing this endpoint. For more information about the new group system, see the Groups and Sections description.

    ⚠️ You need to precise which businesses are part of the group when updating it using the business__in parameter. If don't precise any business, the group will be updated with all the businesses. If you want to update a group to be empty, you can just put an empty array in the business__in parameter.

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

    Name of the group. Cannot include any of the following characters: ,;/

    business__in
    required
    Array of strings (business_ids)

    List of business ids

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "France",
    • "business__in": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "id": 1
    }

    Get Group

    Get a group and it's associated business IDs.
    For more information about the new group system, see the Groups and Sections description.

    Authorizations:
    ApiKeyAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": 1,
    • "name": "France",
    • "has_puller": true,
    • "business_ids": [
      ]
    }

    Delete Group

    Delete a group.
    This endpoint endpoint let's you delete an existing group. Only Group Managers and above can use this endpoint. Business Managers are restricted from accessing this endpoint. For more information about the new group system, see the Groups and Sections description.

    Authorizations:
    ApiKeyAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "id": 1
    }

    Holidays

    Holidays Retrieve a list of upcoming holidays for the specified country

    Get holidays

    This endpoint allows you to retrieve a list of upcoming bank holidays for a specified country within the next 365 days. The holidays are ordered based on their occurrence dates.

    Authorizations:
    ApiKeyAuth
    path Parameters
    country
    required
    string
    Example: FR

    Country code from ISO 3166 international standard - https://www.iban.com/country-codes

    query Parameters
    lang
    string
    Enum: "fr" "en" "es" "it" "pt-br" "de" "ar"
    Example: lang=fr

    Preferred language for holiday names. If no language is provided, the user's default language will be used. If the user's default language is unavailable, the country's primary language will be used.

    Responses

    Response samples

    Content type
    application/json
    {
    • "holidays": [
      ]
    }

    Messages

    ⚠️ This feature is available only for businesses subscribed to the Messages Product. ⚠️ All the operations you can perform on Messages and Conversations.

    Conversations happens between a Business and a consumer that wants to get in touch with the business.

    A Consumer can reach out to the business on one of the supported messaging channels (Google, Facebook, Instagram, SMS). It will then create a new Conversation.

    ⚠️ When dealing with Instagram conversations, there are some requirements that you have to follow :

    • You must not store consumer media (images, stories, ...). You can store the media URL, but not it's content.
    • If you store conversation messages, you must also implement the Message Deleted webhook. When a Message Deleted event is received, you must delete the stored content of the message.

    List conversations

    This endpoint lets you list all the Conversations you have access to.

    You can filter the conversations based on the Organisation or the Business that they are related to.

    If you want to keep an up-to-date list of ongoing conversations for your businesses, we recommend using the Message Received and Message Deleted Webhooks instead of periodically calling this endpoint.

    ⚠️ This endpoint is paginated using cursor pagination. This means that in order to get the next page of results, you need to provide the cursor returned in the previous call.

    Authorizations:
    ApiKeyAuth
    query Parameters
    per_page
    integer [ 1 .. 100 ]
    Default: 30

    Number of items to return per page.

    cursor
    string

    The cursor identifiying the page of data to fetch. If no cursor is provided, the query will return the first page of data. A cursor for the next page of data is provided in the response of this request.

    business__in
    Array of strings (BusinessId)
    Example: business__in=5409c35a97bbc544d8e26737

    Filter by business ids

    Responses

    Response samples

    Content type
    application/json
    {
    • "conversations": [
      ],
    • "count": 1,
    • "next_cursor": "string"
    }

    Conversation information

    This endpoint returns all information on a specific Conversation.

    Authorizations:
    ApiKeyAuth
    path Parameters
    conversation_id
    integer

    The id of the conversation to fetch

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": 0,
    • "consumer_img": "https://www.example.com/profile-picture.jpg",
    • "consumer_name": "John Doe",
    • "consumer_phone_number": "+33612345678",
    • "last_message": {
      },
    • "is_read": true,
    • "status": "Open",
    • "created_at": "2023-01-31 16:22:17.327878+00:00",
    • "has_one_user_message": true,
    • "business": {
      },
    • "messaging_partner": "Google",
    • "issues": [
      ],
    • "first_message_date": "string",
    • "is_expired": false,
    • "is_solved": false,
    • "assigned_user_id": "62d80fae74e8b11d700302b8"
    }

    Update conversation Deprecated

    Please use POST /converations/{conversation_id}/read or PATCH /converations/{conversation_id} instead.

    The only updatable field is "is_read". It will be set for the user that performs the request ("is_read" may have different values for different users).

    Authorizations:
    ApiKeyAuth
    path Parameters
    conversation_id
    integer

    The id of the conversation to update

    Request Body schema: application/json
    is_read
    boolean

    Whether the last message received was read. This property is scoped to the user who performs the request. Multiple users can have a different is_read status for the same conversation.

    Responses

    Request samples

    Content type
    application/json
    {
    • "is_read": true
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success"
    }

    Update conversation

    This endpoint lets you change the status of the conversation to "open" or "closed" and assign it to a user.

    Authorizations:
    ApiKeyAuth
    path Parameters
    conversation_id
    integer

    The id of the conversation to update

    Request Body schema: application/json
    status
    string
    Enum: "open" "closed"

    You can close or re-open the conversation. It will change the "is_solved" boolean of the conversation but it won't change the "is_expired". If the conversation is expired we can't re-open it.

    assigned_user_id
    string
    Enum: "USER_ID" "unassigned"

    Only for enterprise organizations. The user will be assigned to the conversation.

    You can only assign a conversation to a user that:

    • is active
    • is of type human (not bot)
    • has access to the conversation

    Responses

    Request samples

    Content type
    application/json
    {
    • "status": "open",
    • "assigned_user_id": "USER_ID"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success"
    }

    Read conversation

    This endpoint lets you mark a conversation as read. It will be set for the user that performs the request ("is_read" may have different values for different users).

    Authorizations:
    ApiKeyAuth
    path Parameters
    conversation_id
    integer

    The id of the conversation to update

    Request Body schema: application/json
    is_read
    boolean

    Whether the last message received was read. This property is scoped to the user who performs the request. Multiple users can have a different "is_read" status for the same conversation.

    Responses

    Request samples

    Content type
    application/json
    {
    • "is_read": true
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success"
    }

    List messages

    This endpoint lets you retrieve the messages for a specific conversation.

    ⚠️ This endpoint is paginated using cursor pagination. This means that in order to get the next page of results, you need to provide the cursor returned in the previous call.

    Authorizations:
    ApiKeyAuth
    query Parameters
    conversation_id
    required
    integer

    The id of the conversation

    per_page
    integer [ 1 .. 100 ]
    Default: 30

    Number of items to return per page.

    cursor
    string

    The cursor identifiying the page of data to fetch. If no cursor is provided, the query will return the first page of data. A cursor for the next page of data is provided in the response of this request.

    Responses

    Response samples

    Content type
    application/json
    {
    • "messages": [
      ],
    • "count": 1,
    • "next_cursor": "string"
    }

    Send message

    This endpoint allows you to send a message as a business in an existing conversation.

    There are two types of message content supported when sending messages :

    • Text
    • Image

    ⚠️ Because of underlying channel limitations, the Image content_type is not supported for SMS conversations.

    ⚠️ The image size should not exceed 5Mo.

    ⚠️ To send an Image message, you have two ways which uses different type of request body schema (See "REQUEST BODY SCHEMA" below):

    • with application/json: the url of the image.
    • with multipart/form-data: the image file.

    If you want to know if the answer has been send successfully, we recommend using the Message Status Update Webhook.

    If the answer has failed to be sent, you can send it again by using the /retry endpoint

    Authorizations:
    ApiKeyAuth
    Request Body schema:
    Any of
    conversation_id
    required
    integer

    The id of the conversation

    content_type
    required
    string
    Value: "Text"
    content
    required
    string

    The text to send

    Responses

    Request samples

    Content type
    Example
    {
    • "conversation_id": 0,
    • "content_type": "Text",
    • "content": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "message_id": 0
    }

    Retry send message

    This endpoint let you retry sending a message that has failed to be sent.

    Authorizations:
    ApiKeyAuth
    path Parameters
    message_id
    required
    integer

    The id of the message to send

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success"
    }

    Messaging Settings

    All the operations you can perform on Messaging Settings.

    Messaging settings encapsulates all options available to customize the Partoo messaging experience, for a specific Business.

    • welcome message
    • offline messages
    • chat hours
    • launch status

    Messaging Settings are automatically created for businesses subscribed to the Messages Product.

    ⚠️ This feature is available only for businesses subscribed to the Messages product. ⚠️

    List messaging settings

    This endpoint lets you list all the Messaging Settings you have access to.

    You can filter the Messaging Settings based on the Organisation or the Business that they are related to.

    Authorizations:
    ApiKeyAuth
    query Parameters
    page
    integer >= 1
    Default: 1

    Current page number.

    per_page
    integer [ 1 .. 100 ]
    Default: 30

    Number of items to return per page.

    business__in
    Array of strings (BusinessId)
    Example: business__in=5409c35a97bbc544d8e26737

    Filter by business ids

    Responses

    Response samples

    Content type
    application/json
    {
    • "settings": [
      ],
    • "page": 1,
    • "count": 1,
    • "max_page": 1
    }

    Update messaging settings

    This endpoint lets you update a specific Messaging Settings.

    Authorizations:
    ApiKeyAuth
    path Parameters
    setting_id
    integer

    The id of the Messaging Settings to update

    Request Body schema: application/json
    welcome_message
    string or null non-empty

    When a consumer first contacts the business, an automated reply is sent. The content of the reply depends on whether the consumer contacted the business during it's chat hours. If it is, the welcome_message is sent as a reply.

    The welcome_message is mandatory, and can be customized. A default will be set if none is specified.

    offline_message
    string or null non-empty

    When a consumer first contacts the business, an automated reply is sent. The content of the reply depends on whether the consumer contacted the business during it's chat hours. If it is not, the offline_message is sent as a reply.

    The offline_message is mandatory, and can be customized. A default will be set if none is specified.

    uses_business_hours
    boolean or null

    If set to true, the business' "open_hours" will be used as chat hours. Otherwise, you need to specify "custom_chat_hours".

    object or null

    The chat hours of the business (in its timezone).

    Chat hours are specified per weekday. This is done by supplying an object mapping weekdays ("monday", "tuesday", etc.) to a list of strings. These strings in turn represent time slots during which the business is open.

    For example, the following value would set the chat hours to between 08:00-15:00 in the afternoon and 18:00-23:00 in the evening on Mondays:

    {"monday": ["08:00-15:00", "18:00-23:00"]}

    To indicate that a business can be contacted for 24 hours, for a specific weekday, use the value ["00:00-23:59"].

    This field is not mandatory unless "uses_business_hours" is set to false.

    is_launched
    boolean or null

    Some messaging channels (Google and Facebook) can be temporarily deactivated. This allows the business to close for a period of time without having to answer consumer messages.

    This is important because consumers will get frustrated if they are able to contact a business and do not get an answer. It is also important to note that for some messaging channels, not responding to messages may lead to decreased visibility of the business, or suspension of the messaging service.

    The is_launched property indicates whether the business is reachable for those messaging channels.

    The value can be updated, and the changes will be propagated to the messaging channels, effectively toggling the On or Off the ability for consumers to reach the business. (The change to "is_launched" is made asychronously, and the update will be effective when the messaging channels have finished propagating the information)

    Responses

    Request samples

    Content type
    application/json
    {
    • "welcome_message": "string",
    • "offline_message": "string",
    • "uses_business_hours": true,
    • "custom_chat_hours": {
      },
    • "is_launched": true
    }

    Response samples

    Content type
    application/json
    {
    • "id": 0,
    • "business_id": "string",
    • "business_name": "string",
    • "business_address": "1 Rue de la Paix, 75000 Paris",
    • "welcome_message": "string",
    • "offline_message": "string",
    • "uses_business_hours": true,
    • "custom_chat_hours": {
      },
    • "is_launched": true
    }

    Organisations

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

    Search for organisations

    This endpoint lets you search for organisations using filters. The response is paginated (30 results per page).

    Authorizations:
    ApiKeyAuth
    query Parameters
    org_id
    integer

    Organisation id

    page
    integer
    Default: 0

    Page number. 30 results per page

    Responses

    Response samples

    Content type
    application/json
    {
    • "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:
    ApiKeyAuth
    Request Body schema: application/json
    name
    required
    string (OrgName)

    Organisation name

    alias
    string (OrgAlias)

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

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "Fast Retailer",
    • "alias": "fast_retailer"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "org_id": 42,
    • "alias": "fast_retailer"
    }

    Organisation information

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

    Authorizations:
    ApiKeyAuth
    path Parameters
    org_id
    required
    integer

    Organisation id

    Responses

    Response samples

    Content type
    application/json
    {
    • "org_id": 42,
    • "name": "Fast Retailer",
    • "alias": "fast_retailer",
    • "provider": "partoo",
    • "type": "small_medium_business",
    • "has_google_post": true,
    • "display_google_post": true,
    • "last_org_api_call": "05-11-2021"
    }

    Update organisation

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

    Authorizations:
    ApiKeyAuth
    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

    Request samples

    Content type
    application/json
    {
    • "name": "Fast Retailer",
    • "alias": "fast_retailer"
    }

    Response samples

    Content type
    application/json
    {
    • "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:
    ApiKeyAuth
    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

    Request samples

    Content type
    application/json
    {
    • "force": "True"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "org_id": 42
    }

    Posts

    Post is a feature that allows businesses to create and share announcements, offers, new or popular items in stock, or event details directly with the customers. The post will appear on the specified partner, which will boost the results for the business.

    When a business is connected to a Google location (action performed in Partoo app on Partner Connection page), all the Google Posts will be automatically imported. When a business is disconnected the Google Posts published on Google will be deleted from Partoo database.


    ⚠️ -- Google Post -- ⚠️
    ⚠️ Feature only available for small and midsize businesses (SMBs) ⚠️

    Google Posts is a feature that allows businesses to create and share announcements, offers, new or popular items in stock, or event details directly with the customers. The post will appear on Google Search and Maps, which will boost the results for the business.

    When a business is connected to a Google location (action performed in Partoo app on Partner Connection page), all the Google Posts will be automatically imported. When a business is disconnected the Google Posts published on Google will be deleted from Partoo database.

    Search for post

    This endpoint lets you browse through all your posts.

    Authorizations:
    ApiKeyAuth
    query Parameters
    business__in
    Array of strings (BusinessId)
    Example: business__in=5409c35a97bbc544d8e26737

    Filter by business ids

    start_datetime
    string
    Example: start_datetime=2020-11-06T23:59:59

    Filters Posts based on their start datetime.

    The start datetime represents the moment on which a Post of type event/offer will become available. In case of Posts of type news, the start_datetime it will be compare to the creation date of the Post, as the field is not present in this context.

    end_datetime
    string
    Example: end_datetime=2020-11-06T23:59:59

    Filter Posts based on their end datetime.

    The end datetime represents the date on which the Post of type event/offer will expire. In case of Posts of type news, the end_datetime it will be compare to exactly one week after the creation date of the Post, as the field is not present in this context.

    summary
    string

    Filter Posts based on their description.

    It returns Posts that contain in their description the given string. The text does not have to match perfectly.

    state__in
    string
    Enum: "live" "to_configure" "pending" "scheduled" "error" "expired"

    Filter Posts based on its state.

    topic_type
    string
    Enum: "standard" "event" "offer" "alert"

    Filter Posts based on its type.

    topic_type__in
    string
    Enum: "standard" "event" "offer" "alert"

    Filter Posts based on a list of different types.

    Responses

    Response samples

    Content type
    application/json
    {
    • "page": 1,
    • "max_page": 10,
    • "count": 287,
    • "posts": [
      ]
    }

    Create a post

    This endpoint lets you create a post on Google / Facebook.

    The creation will not happen in real time and might take a few minutes.

    Authorizations:
    ApiKeyAuth
    Request Body schema: application/json
    required
    object (PostBusinessSearch)

    Business to create post

    publishers
    required
    Array of strings (PostPublishers)
    Items Enum: "google_my_business" "facebook"

    List of publisher to diffuse the post

    required
    object (PostData)

    Information on post to create

    Responses

    Request samples

    Content type
    application/json
    {
    • "business_search": {
      },
    • "publishers": [
      ],
    • "data": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "code": 200,
    • "message": "2 posts have been created.",
    • "ids": "45,46",
    • "data": [
      ]
    }

    Update a post

    This endpoint lets you update a post. The update will not happen in real time and might take a few minutes

    Authorizations:
    ApiKeyAuth
    path Parameters
    post_id
    required
    number

    Post id

    Request Body schema: application/json
    title
    string (postTitle)

    Title of the post.

    summary
    string (postSummary)

    Main text content of the post.

    image_url
    string (postImageURL)

    URL of the image displayed with the post.

    cta_type
    string (postCTAType)
    Enum: "book" "order" "shop" "learn_more" "sign_up" "call" "no_cta"

    The type of the post to be created. Some type mig.

    object (postLink)

    Link displayed in the post to redirect the client clicking on it. Use can only have one of the following parameters ('use_business_url' or 'custom_url').

    schedule_time
    datetime (postScheduleTime)

    Date and time of when the post will be diffused corresponding platforms. It needs to be at least 2 hours after the time of the request. The timezone used is UTC.

    start_at
    datetime (postStartAt)

    For either event or offer post type. Defined when it start. Timezone is defined by the business timezone.

    end_at
    datetime (postEndAt)

    For either event or offer post type. Defined when it end. Timezone is defined by the business timezone.

    coupon_code
    string (postCouponCode)

    Offer code that is usable in store or online

    offer_terms
    string (postOfferTerms)

    Terms and conditions of the offer

    Responses

    Request samples

    Content type
    application/json
    {
    • "title": "Great post title !",
    • "summary": "Wonderful post summary !",
    • "image_url": "wxx",
    • "cta_type": "book",
    • "link": {
      },
    • "schedule_time": "2050-01-01T09:00:00",
    • "start_at": "2050-01-01T09:00:00",
    • "end_at": "2050-01-01T09:00:00",
    • "coupon_code": "PROMO25",
    • "offer_terms": "These are the conditions"
    }

    Response samples

    Content type
    application/json
    {
    • "id": 34,
    • "business_id": "5409c35a97bbc544d8e26737",
    • "post_type": "news",
    • "summary": "Wonderful post summary !",
    • "schedule_time": "2020-01-01T12:00:00+02:00",
    • "post_medias": [
      ],
    • "created_at": "2019-08-01T19:15:54.256000+02:00",
    • "updated_at": "2019-09-01T15:12:35.256000+02:00",
    • "created_on_partoo": false,
    • "updated_on_partoo": false,
    • "business_info": "Rick - HQ - 157 boulevard Macdonald, Paris",
    • "post_insight": [
      ],
    • "post_status": [
      ],
    • "offer_terms": "These are the conditions",
    • "offer_code": "PROMO25",
    • "cta_link": "www.partoo.co",
    • "cta_type": "book"
    }

    Delete a post

    This endpoint lets you delete a post.

    The deletion will not happen in real time and might take a few minutes.

    Authorizations:
    ApiKeyAuth
    path Parameters
    post_id
    required
    number

    Post id

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success"
    }

    Search for Google post Deprecated

    This endpoint lets you browse through all your Google Posts.

    Authorizations:
    ApiKeyAuth
    query Parameters
    business__in
    Array of strings (BusinessId)
    Example: business__in=5409c35a97bbc544d8e26737

    Filter by business ids

    start_datetime
    string
    Example: start_datetime=2020-11-06T23:59:59

    Filters Google Posts based on their start datetime.

    The start datetime represents the moment on which a Google Post of type event/offer will become available. In case of Google Posts of type news, the start_datetime it will be compare to the creation date of the Google Post, as the field is not present in this context.

    end_datetime
    string
    Example: end_datetime=2020-11-06T23:59:59

    Filter Google Posts based on their end datetime.

    The end datetime represents the date on which the Google Post of type event/offer will expire. In case of Google Posts of type news, the end_datetime it will be compare to exactly one week after the creation date of the Google Post, as the field is not present in this context.

    is_expired
    boolean

    Filter Google Posts based on whether or not it has expired.

    title
    string

    Filter Google Posts based on their title.

    It returns Google Posts that contain in their title the given string. The text does not have to match perfectly.

    summary
    string

    Filter Google Posts based on their description.

    It returns Google Posts that contain in their description the given string. The text does not have to match perfectly.

    state__in
    string
    Enum: "LIVE" "PARTOO_PENDING" "PARTOO_PENDING_DELETE" "PROCESSING" "REJECTED" "PARTOO_SCHEDULED" "PARTOO_ERROR"

    Filter Google Posts based on its state.

    topic_type
    string
    Enum: "NEWS" "EVENT" "OFFER" "ALERT"

    Filter Google Posts based on its type.

    topic_type__in
    string
    Enum: "NEWS" "EVENT" "OFFER" "ALERT"

    Filter Google Posts based on a list of different types.

    Responses

    Response samples

    Content type
    application/json
    {
    • "page": 1,
    • "max_page": 10,
    • "count": 287,
    • "google_post": [
      ]
    }

    Create a Google post Deprecated

    This endpoint lets you create a Google Post.

    The creation will not happen in real time and might take a few minutes.

    Authorizations:
    ApiKeyAuth
    query Parameters
    business__in
    Array of strings (BusinessId)
    Example: business__in=5409c35a97bbc544d8e26737

    Filter by business ids

    Request Body schema: application/json
    topic_type
    required
    string (GooglePostTopicType)
    Enum: "NEWS" "EVENT" "OFFER" "ALERT"

    The type of the Google Post. A Google Post cannot have multiple types.

    summary
    required
    string (GooglePostSummary)

    The description of the Google Post.

    media_url
    string (GooglePostMediaUrl)

    The url of the photo of the Google Post.

    call_to_action_type
    string (GooglePostCallToActionType)
    Default: "learn_more"
    Enum: "book" "order" "shop" "learn_more" "sign_up" "call" "no_cta"

    Google Posts can have an additional button displayed so that the user can book a reservation or order online. The no_cta option means that you do not want a call to action button.

    call_to_action_url
    string (GooglePostCallToActionUrl)

    The url that will be used for redirection when clicking on the call to action button. In case of call or no_cta for call_to_action_type, this parameter is not needed.

    use_business_url
    boolean

    To use the business url of the business instead of a specific one for a call_to_action_url.

    In case of bulk creations, the business url of each business will be used for its specific Google Post

    scheduled_start_time
    string

    Date when the Google Post will be published.

    If not given, the default value is now, therefore the Google Post will be published immediatly. The timezone is mandatory.

    required
    object (GooglePostEvent)

    Google Post Event, required only for event and offer topic types.

    required
    object (GooglePostOffer)

    Google Post Offer, required only for offer topic type.

    Responses

    Request samples

    Content type
    application/json
    {
    • "topic_type": "OFFER",
    • "summary": "Your business will now open until 20:00",
    • "media_url": "https://www.my-photo.jpeg",
    • "call_to_action_type": "book",
    • "call_to_action_url": "https://www.partoo.co",
    • "use_business_url": false,
    • "scheduled_start_time": "2020-01-01T12:00:00+02:00",
    • "google_post_event": {
      },
    • "google_post_offer": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success"
    }

    Specific Google post Deprecated

    This endpoint returns all information on a specific Google Post.

    Authorizations:
    ApiKeyAuth
    path Parameters
    google_post_id
    required
    number

    Google Post id

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": 34,
    • "business_id": "5409c35a97bbc544d8e26737",
    • "topic_type": "OFFER",
    • "summary": "Your business will now open until 20:00",
    • "scheduled_start_time": "2020-01-01T12:00:00+02:00",
    • "google_post_event": {
      },
    • "google_post_offer": {
      },
    • "google_post_media": {},
    • "created_at": "2019-08-01T19:15:54.256000+02:00",
    • "updated_at": "2019-09-01T15:12:35.256000+02:00",
    • "language_code": "string",
    • "view_count": 200,
    • "click_count": 155,
    • "state": "live",
    • "created_on_partoo": true,
    • "updated_on_partoo": true,
    • "search_url": "string",
    • "business_info": "string",
    • "google_creation_date": "string",
    • "is_expired": true
    }

    Update a Google post Deprecated

    This endpoint lets you update a Google Post. The update will not happen in real time and might take a few minutes

    Authorizations:
    ApiKeyAuth
    path Parameters
    google_post_id
    required
    number

    Google Post id

    Request Body schema: application/json
    summary
    string (GooglePostSummary)

    The description of the Google Post.

    media_url
    string (GooglePostMediaUrl)

    The url of the photo of the Google Post.

    call_to_action_type
    string (GooglePostCallToActionType)
    Default: "learn_more"
    Enum: "book" "order" "shop" "learn_more" "sign_up" "call" "no_cta"

    Google Posts can have an additional button displayed so that the user can book a reservation or order online. The no_cta option means that you do not want a call to action button.

    call_to_action_url
    string (GooglePostCallToActionUrl)

    The url that will be used for redirection when clicking on the call to action button. In case of call or no_cta for call_to_action_type, this parameter is not needed.

    scheduled_start_time
    string

    Date when the Google Post will be published (will be publish immediatly by default). The timezone is mandatory. This field can be modify only if the post has not been created yet.

    object (GooglePostEvent)

    Google Post Event, required only for event and offer topic types.

    object (GooglePostOffer)

    Google Post Offer, required only for offer topic type.

    Responses

    Request samples

    Content type
    application/json
    {
    • "summary": "Your business will now open until 20:00",
    • "media_url": "https://www.my-photo.jpeg",
    • "call_to_action_type": "book",
    • "call_to_action_url": "https://www.partoo.co",
    • "scheduled_start_time": "2020-01-01T12:00:00+02:00",
    • "google_post_event": {
      },
    • "google_post_offer": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": 34,
    • "business_id": "5409c35a97bbc544d8e26737",
    • "topic_type": "OFFER",
    • "summary": "Your business will now open until 20:00",
    • "scheduled_start_time": "2020-01-01T12:00:00+02:00",
    • "google_post_event": {
      },
    • "google_post_offer": {
      },
    • "google_post_media": {},
    • "created_at": "2019-08-01T19:15:54.256000+02:00",
    • "updated_at": "2019-09-01T15:12:35.256000+02:00",
    • "language_code": "string",
    • "view_count": 200,
    • "click_count": 155,
    • "state": "live",
    • "created_on_partoo": true,
    • "updated_on_partoo": true,
    • "search_url": "string",
    • "business_info": "string",
    • "google_creation_date": "string",
    • "is_expired": true
    }

    Delete a Google post Deprecated

    This endpoint lets you delete a Google Post.

    The deletion will not happen in real time and might take a few minutes.

    Authorizations:
    ApiKeyAuth
    path Parameters
    google_post_id
    required
    number

    Google Post id

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success"
    }

    Presence

    All operations available on Presence Listing Page.

  • GET /v2/presence_analytics
    • [An Internal Link to a Section Heading](#Review and presence analytics).

    BusinessInfo Deprecated

    Method to retrieve business information given a publisher and the state on this publisher

    Can be filtered by:

    • The state of the publisher
    • The name of the publisher
    Authorizations:
    ApiKeyAuth
    path Parameters
    business_id
    required
    string

    Business id

    query Parameters
    publisher_names
    Array of strings
    Example: publisher_names=facebook,google_my_business

    List of requested publisher names

    states
    Array of enum (state)
    Items Enum: "success" "pending" "to_configure"
    Example: states=success,to_configure,pending

    List of the requested states

    Responses

    Response samples

    Content type
    application/json
    {
    • "facebook": {
      },
    • "google_my_business": {
      }
    }

    BusinessesInfo Deprecated

    Method to retrieve paginated businesses information given a publisher and the state on this publisher

    Can be filtered by:

    • Business IDs
    Authorizations:
    ApiKeyAuth
    query Parameters
    business__in
    Array of strings (BusinessId)
    Example: business__in=5409c35a97bbc544d8e26737

    Filter by business ids

    publisher_name
    required
    string
    Example: publisher_name=google_my_business

    Name of the requested publisher

    state
    required
    enum (state)
    Enum: "success" "pending" "to_configure"
    Example: state=success

    State requested

    page
    integer
    Example: page=3

    Page requested

    Responses

    Response samples

    Content type
    application/json
    {
    • "facebook": {
      }
    }

    PublisherStates

    Method to retrieve businesses diffusions states on publishers.

    Can be filtered by:

    • Business IDs
    • Publishers
    • States
    Authorizations:
    ApiKeyAuth
    query Parameters
    business__in
    Array of strings (BusinessId)
    Example: business__in=5409c35a97bbc544d8e26737

    Filter by business ids

    publishers
    Array of strings
    Example: publishers=facebook,google_my_business

    List of requested publisher names

    states
    Array of enum (state)
    Items Enum: "success" "pending" "to_configure"
    Example: states=success,to_configure,pending

    List of the requested states

    per_page
    integer [ 1 .. 100 ]
    Default: 5

    Number of items to return per page. Currently limited to 100.

    page
    integer
    Example: page=3

    Page requested

    Responses

    Response samples

    Content type
    application/json
    {
    • "businesses": {
      },
    • "count": 1
    }

    PublisherErrors

    This method retrieve a list of known errors associated with a publisher for a business, including detailed descriptions.

    The request body is mandatory.

    Providing an empty request body will return errors based on the business information stored in the database.

    Providing a populated request body will return errors related to the specified fields and their values only.

    Authorizations:
    ApiKeyAuth
    path Parameters
    business_id
    required
    string

    Business id

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

    The name of the business (POI) as it will appear on the publishing platforms

    org_id
    integer (BusinessOrgId)

    The organisation unique identifier at Partoo. During onboarding, Partoo creates an organisation where all your businesses will be aggregated

    country
    string (BusinessCountry)

    Business country - In the ISO 3166 alpha2 code format (i.e. use “FR” for France instead of "fr")

    zipcode
    string (BusinessZipcode)

    Zipcode (or postal code) for the business address. Can be empty if the business' country does not require one.

    city
    string (BusinessCity)

    The city where the business is located

    region
    string (BusinessRegion)

    The region where the business is located. Can be empty, it is only useful for some countries like Italy or Spain among others.

    categories
    Array of arrays (BusinessCategories)

    A list of category ids mapped to the business. At least one category needs to be provided. For more information see Categories section

    code
    string (BusinessCode)

    The unique store code of the business. If not provided, it will be automatically generated

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

    Defines the current status of the business. open indicates the business is up and running. closed means that the business has definitely closed. temporarily_closed means that the business is temporarily closed, it is advised when your business is closed for more than one week, otherwise use the specific_hours

    address_full
    string (AddressFull)

    Full address of the business.

    For example : 130 Rue du Mont-Cenis.

    address2
    string (Address2)

    Complement of address. Any additional information that could help better find the business location

    manual_lat
    number <double> (BusinessLatitude)

    Latitude. Decimals are separated by a dot and not by a comma.

    manual_long
    number <double> (BusinessLongitude)

    Longitude. Decimals are separated by a dot and not by a comma.

    lat
    number <double> (BusinessLatitude)

    Latitude. Decimals are separated by a dot and not by a comma.

    long
    number <double> (BusinessLongitude)

    Longitude. Decimals are separated by a dot and not by a comma.

    website_url
    string <uri> (BusinessWebsite)

    The business own website url or the main url of the company.

    facebook_url
    string <uri> (BusinessFacebookPage)

    Business Facebook page url

    twitter_url
    string <uri> (BusinessTwitter)

    Business twitter page url

    description_short
    string (BusinessShortDescription)

    A short description of the business. It needs to be in the language of the country where the business is located. For example, if the business is located in Madrid, then the description needs to be in Spanish.

    ⚠️It is limited to 200 characters

    description_long
    string (BusinessLongDescription)

    A more detailed description of the business. It needs to be in the language of the country where the business is located. For example, if the business is located in London, then the description needs to be in English.

    ⚠️It is limited to 750 characters

    object (OpenHours)

    The opening hours of the business (in its timezone).

    Opening hours are specified per weekday. This is done by supplying an object mapping weekdays ("monday", "tuesday", etc.) to a list of of strings. These strings in turn represent time slots during which the business is open.

    For example, the following value would set the opening hours to between 08:00-15:00 in the afternoon and 18:00-23:00 in the evening on Mondays:

    {"monday": ["08:00-15:00", "18:00-23:00"]}

    To indicate that a business is open 24 hours for a specific weekday, use the value ["00:00-23:59"].

    ❗ This field is not mandatory, but if not provided then the business will not be pushed on some platforms (example: Google). If provided, then a schedule needs to be sent for each day in particular

    object (SpecificHours)

    Exceptional opening or closing times for the business (in its timezone).

    All exceptional days of the year, including temporarily closed, can be specified beforehand or on the go. For example:

    • Beforehand: bank holidays (like Christmas or Labor Day)
    • Unpredicted: COVID-19 exceptional situation

    Specific hours are defined by two values:

    • open, containing a list of days with exceptional opening hours
    • close, containing a list of days where the business is exceptionally closed all day.

    These values in turn, contain:

    • starts_at indicating the first date for which the exceptional hours are valid
    • ends_at indicating the last date (inclusive) for which the exceptional hours are valid
    • open_hours (only used for days with exceptional opening hours) indicating the actual time slots for the given period, following the same pattern as the time slots in open_hours
    Array of objects (BusinessContactsCreate)

    Specify how the clients can reach the persons in charge of the business in case they have questions.

    object (Photos)

    Business photos

    Each business can have one or more photos associated

    national_identification_number
    string (BusinessNationalIdentificationNumber)

    The National Identification Number of the business

    It describes a unique number for which the business is registered in a specific country. For example, in France, it's SIRET code or for Ireland it's the CRO

    Responses

    Request samples

    Content type
    application/json
    Example

    Providing an empty request body will return errors based on the business information stored in the database.

    { }

    Response samples

    Content type
    application/json
    Example
    { }

    Reviews

    ⚠️ This feature is available only for businesses subscribed to Review Management. ⚠️

    Partoo centralises all businesses reviews from Google, Facebook and TripAdvisor platforms.

    The reviews are fetched once per day (over night), therefore a it is expected to have a delay of maximum 24h. The Partoo APIs enable a simple way of replying to any new reviews, update an existing reply or delete a reply. A review can have one of the following status:

    • treated: has a reply/comment or it was manually marked as treated in the Partoo UI
    • not-treated: it doesn't have a reply/comment and it was not manually marked as treated in the Partoo UI
    • deleted: the review was removed by the user on the original platfrom.

    Note: the review itself cannot be altered nor deleted via the APIs.

    Reply templates allow business managers to gain time in replying to the reviews, via a predefined answer which can be easily selected and sent.

    Reply templates are not meant to be used outside the Partoo application. For this reason it is not possible to access a formatted template, with prefilled placeholders from the API.

    However it is still possible to browse through, create or delete reply templates from the Partoo API.

    Search for reviews

    This endpoint lets you search for the reviews of your businesses.

    To access the reviews of a business you need to have READ access on it. The response is paginated (30 results per page).

    Authorizations:
    ApiKeyAuth
    query Parameters
    business__in
    Array of strings (BusinessId)
    Example: business__in=5409c35a97bbc544d8e26737

    Filter by business ids

    business__notin
    Array of strings (BusinessId)
    Example: business__notin=5409c35a97bbc544d8e26737

    Excludes from the request all businesses provided

    content__isnull
    string
    Enum: true false
    Example: content__isnull=false

    Filter by review's content

    If set to true, the endpoint will return all the reviews without content.

    Note: This is the content of the review and not the content of the reply.

    partner__in
    Array of strings (ReviewPublisherLabel)
    Items Enum: "google_my_business" "facebook" "tripadvisor"
    Example: partner__in=google_my_business,facebook

    Filter by publisher

    gmb_rating__in
    Array of numbers
    Items Enum: 1 2 3 4 5
    Example: gmb_rating__in=4,5

    Filter only by Google ratings

    tripadvisor_rating__in
    Array of numbers
    Items Enum: 1 2 3 4 5
    Example: tripadvisor_rating__in=1,2

    Filter only by Tripadvisor ratings

    recommended__in
    Array of booleans
    Items Enum: true false
    Example: recommended__in=false

    Filter only by Facebook recommendation

    update_date__gte
    string <datetime>
    Example: update_date__gte=2017-08-01T00:00:00

    Filter by update_date

    Return all the reviews whose update_date >= given_date.

    For example : update_date__gte=2019-01-01T00:00:00 will return all reviews from the first January of 2019 until today.

    Note : The update dates are stored in UTC.

    update_date__lte
    string <datetime>
    Example: update_date__lte=2017-08-02T00:00:00

    Filter by update_date

    Return all the reviews whose update_date <= given_date.

    For example : update_date__lte=2020-01-01T00:00:00 will return all reviews from the date of the first review until the first january of 2020.

    Note : The update dates are stored in UTC.

    state__in
    Array of strings (ReviewState)
    Items Enum: "treated" "not_treated" "deleted"
    Example: state__in=treated,not_treated

    Filter by state

    tag_label__in
    Array of strings (TagLabel)
    Example: tag_label__in=food,drink

    Filter by Tag label

    Will partially match given labels (ie foo will match reviews with tag food)

    without_tag
    boolean
    Enum: true 1
    Example: without_tag=true

    Filter only reviews without tags

    keywords
    Array of strings
    Example: keywords=bonjour,good+service

    Filter by keywords

    Return all the reviews with not-nullable content, that contain the provided list of keywords.

    Note: This is the content of the review and not the content of the reply.

    The filter accepts both simple and composed words. To indicate it's a composed keyword, add the + as separator. For example:

    keywords=bonjour returns all reviews containing the keyword bonjour

    keywords=good+service returns all reviews containing the combined keyword good service, without splitting the keyword. No reviews containing just good or just service will be returned.

    keywords=bonjour,good+service: returns all reviews that contain either just bonjour, either just good service or both keywords at the same time.

    page
    integer
    Default: 1

    Page number, Starts at 1. From 1 to 100 results per page (see per_page)

    per_page
    integer [ 1 .. 100 ]
    Default: 30

    Number of items to return per page. Currently limited to 100.

    order_by
    string
    Enum: "<object>" "-<object>"
    Example: order_by=-queries_direct

    Where object is either a dimension or a metric and is used in the request. At most one in the list. - before a field to order_by DESC, nothing for ASC

    Responses

    Response samples

    Content type
    application/json
    {
    • "page": 1,
    • "max_page": 10,
    • "count": 287,
    • "reviews": [
      ]
    }

    Post a reply to a review

    This endpoint lets you reply to a given review.

    Authorizations:
    ApiKeyAuth
    Request Body schema: application/json
    review_id
    required
    number

    ID of the review you want to reply

    parent_id
    number

    The id of the parent comment you want to reply

    Works only for Facebook comments, since it's possible to reply to a comment (depth max is 2). Google and TripAdvisor don't accept this behaviour.

    content
    required
    string <text>

    Content of your reply

    Responses

    Request samples

    Content type
    application/json
    {
    • "review_id": 34,
    • "parent_id": 1234,
    • "content": "Merci ❤️"
    }

    Response samples

    Content type
    application/json
    {
    • "id": 82938,
    • "partner_id": "accounts/114063712393225091258/locations/74805271119400652054",
    • "created": "2019-08-01T19:15:54.256000+02:00",
    • "author_name": "Castorche",
    • "content": "Merci ❤️",
    • "date": "2017-08-01T19:15:54.256000+02:00",
    • "can_edit": true,
    • "review_id": 34,
    • "parent_id": 0
    }

    Modify a reply to a review

    This endpoint lets you modify a given reply to a review.

    Authorizations:
    ApiKeyAuth
    path Parameters
    comment_id
    required
    integer (CommentId)
    Example: 82938

    Comment id

    Request Body schema: application/json
    content
    required
    string <text>

    Content of your Reply

    Responses

    Request samples

    Content type
    application/json
    {
    • "content": "Merci ❤️"
    }

    Response samples

    Content type
    application/json
    {
    • "id": 82938,
    • "partner_id": "accounts/114063712393225091258/locations/74805271119400652054",
    • "created": "2019-08-01T19:15:54.256000+02:00",
    • "author_name": "Castorche",
    • "content": "Merci ❤️",
    • "date": "2017-08-01T19:15:54.256000+02:00",
    • "can_edit": true,
    • "review_id": 34,
    • "parent_id": 0
    }

    Delete the given reply to a review

    This endpoint lets you delete the reply to a review

    Authorizations:
    ApiKeyAuth
    path Parameters
    comment_id
    required
    integer (CommentId)
    Example: 82938

    Comment id

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success"
    }

    Search for review reply templates

    This endpoint lets you browse through all your reply review templates.

    Authorizations:
    ApiKeyAuth
    query Parameters
    page
    integer
    Default: 0

    Page number. 30 results per page

    positive
    boolean

    Filter on templates made to answer positive reviews (ex from 4 to 5 stars on gmb).

    neutral
    boolean

    Filter on templates made to answer neutral reviews (ex 3 stars on gmb).

    negative
    boolean

    Filter on templates made to answer negative reviews (ex from 1 to 2 stars on gmb).

    language__in
    Array of strings (Lang)
    Items Enum: "fr" "en" "es" "it" "pt-br" "de" "ar"
    Example: language__in=fr,it

    Filter on templates in the specified languages.

    title_query
    string

    Filter on templates based on their title

    text_query
    string

    Filter on templates based on their text

    Responses

    Response samples

    Content type
    application/json
    {
    • "page": 1,
    • "max_page": 10,
    • "count": 287,
    • "reply_templates": [
      ]
    }

    All available placeholders

    This endpoint lets you access available placeholders for reply review templates. A template placeholder is a dynamically updated word within the Partoo app depending on the context.

    Ex: Once used to answer a review, if a template has a client_first_name placeholder, the placeholder will take the value of the reviewer's first name.

    Authorizations:
    ApiKeyAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": 2,
    • "value": "my_first_name"
    }

    Create a review reply template

    This endpoint lets you create a review reply template.

    Authorizations:
    ApiKeyAuth
    Request Body schema: application/json
    language
    required
    string (Lang)
    Enum: "fr" "en" "es" "it" "pt-br" "de" "ar"

    Available language in the application

    negative
    required
    boolean (TemplateNegative)

    Template is made for negative reviews (ex from 1 to 2 stars on gmb)

    neutral
    required
    boolean (TemplateNeutral)

    Template is made for neutral reviews (ex 3 stars on gmb)

    positive
    required
    boolean (TemplatePositive)

    Template is made for positive reviews (ex from 4 to 5 stars on gmb)

    text
    required
    string (TemplateText)

    The content of the reply template.

    Placeholders are recognisable within the text by this exact markup @[](name_of_the_placeholder). Where name_of_the_placeholder is the value field taken from the GET placeholders operation.

    Example of usable placeholder values: client_full_name, client_first_name, business_name, my_first_name.

    title
    required
    string (TemplateTitle)

    Template title

    Responses

    Request samples

    Content type
    application/json
    {
    • "language": "fr",
    • "negative": true,
    • "neutral": true,
    • "positive": true,
    • "text": "hello @[](client_full_name),\nThanks from the team at @[](business_name).\n@[](my_first_name)",
    • "title": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "id": 34,
    • "org_id": 42,
    • "update_date": "2017-08-01T19:15:54.256000+02:00",
    • "creation_date": "2017-08-01T19:15:54.256000+02:00",
    • "language": "fr",
    • "title": "string",
    • "text": "hello @[](client_full_name),\nThanks from the team at @[](business_name).\n@[](my_first_name)",
    • "negative": true,
    • "neutral": true,
    • "positive": true
    }

    Delete a review reply template

    This endpoint lets you delete a review reply template given its id.

    Authorizations:
    ApiKeyAuth
    path Parameters
    template_id
    required
    number

    Template id

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success"
    }

    Review and presence analytics

    All the operations to perform analytics on Presence Management and Reviews analytics.

    Presence analytics Deprecated

    This endpoint lets you view the Google analytics for all your businesses subscribed to Presence Management. The API allows you to select what data you're interested in, and how you want it aggregated (daily, monthly, by business, etc). You can also filter the results to limit it to a certain date range, and to certain business.

    Google doesn't provide reliable data for the most recent 5 days.

    You can choose the analytics you want to get among:

    • queries: direct, indirect, branded or discovery
    • views: maps or search
    • actions: website, phone or driving directions

    You can use the following filters:

    • by businesses (businesses id in list or not in list)
    • by date (analytics before and/or after a date)
    • by business query. Will return matches for the business name, zipcode or city
    • by business city.

    The response can be aggregated by:

    • business id
    • by date: either by day, week, month or year
    • by both business id and date

    The response can be ordered in ascending or descending order by any of the selected dimensions or metrics. See examples for more details.

    Authorizations:
    ApiKeyAuth
    query Parameters
    metrics
    required
    string
    Enum: "queries_direct" "queries_indirect" "queries_branded" "queries_discovery" "views_maps" "views_search" "actions_website" "actions_phone" "actions_driving_directions"
    Example: metrics=queries_direct

    List of analytics to return. At least one in that list.

    dimensions
    string
    Enum: "business" "day" "week" "month" "year"

    How the returned data will be aggregated. At most 'business' and one time dimensions of the list. If no dimension is given, the request will return the sum of each metric for all requested days and businesses.

    order_by
    string
    Enum: "<object>" "-<object>"
    Example: order_by=-queries_direct

    Where object is either a dimension or a metric and is used in the request. At most one in the list. - before a field to order_by DESC, nothing for ASC

    business__in
    Array of strings (BusinessId)
    Example: business__in=5409c35a97bbc544d8e26737

    Filter by business ids

    business__notin
    Array of strings (BusinessId)
    Example: business__notin=5409c35a97bbc544d8e26737

    Excludes from the request all businesses provided

    city
    string

    Filter by city

    query
    string

    Parameter to fuzzy search businesses on city, zipcode and name

    filter_date__gte
    string <datetime>

    Filter by date

    Return all the analytics whose date >= given_date.

    filter_date__lte
    string <datetime>

    Filter by date. Return all the analytics whose filter_date <= given_date.

    Responses

    Response samples

    Content type
    application/json
    Example
    [
    • {
      }
    ]

    Export analytics Deprecated

    This endpoint let you export the analytics of your businesses. You need to choose an email address on which you will receive a mail to download the Excel file generated. To access the analytics of a business, you need to:

    • have READ access on it
    • have subscribed to Presence Management for this business. You can access the analytics from Google. Data of the past 5 days are not available because they are not given by Google.

    You will receive the following analytics:

    • queries: direct, indirect, branded or discovered
    • views: maps or search
    • actions: website, phone or driving direction

    You can use the following filters:

    • by businesses (businesses id in list or not in list)
    • by date (analytics before and/or after a date)
    • by query in business name, zipcode or city
    • by city.

    The response can be aggregated by:

    • business
    • by date: day, week, month or year
    • business and time

    The response can be ordered by:

    • business id
    • by date: day, week, month or year
    • metrics

    The parameters shall be used the same way than parameters of the endpoint 'Search for analytics'. Please refer to that endpoint for examples.

    Authorizations:
    ApiKeyAuth
    query Parameters
    email
    required
    string <email>
    Example: email=perceval@kaamelott.com

    email address the export will be sent to

    dimensions
    string
    Enum: "business" "day" "week" "month" "year"

    How the returned data will be aggregated. At most 'business' and one time dimensions of the list. If no dimension is given, the request will return the sum of each metric for all requested days and businesses.

    order_by
    string
    Enum: "<object>" "-<object>"
    Example: order_by=-queries_direct

    Where object is either a dimension or a metric and is used in the request. At most one in the list. - before a field to order_by DESC, nothing for ASC

    business__in
    Array of strings (BusinessId)
    Example: business__in=5409c35a97bbc544d8e26737

    Filter by business ids

    business__notin
    Array of strings (BusinessId)
    Example: business__notin=5409c35a97bbc544d8e26737

    Excludes from the request all businesses provided

    city
    string

    Filter by city

    query
    string

    Parameter to fuzzy search businesses on city, zipcode and name

    filter_date__gte
    string <datetime>

    Filter by date

    Return all the analytics whose date >= given_date.

    filter_date__lte
    string <datetime>

    Filter by date. Return all the analytics whose filter_date <= given_date.

    Responses

    Response samples

    Content type
    application/json
    "success"

    Profile metrics for your business

    This endpoint lets you view the Google Business Profile analytics for all your businesses subscribed to Presence Management. The API allows you to select what data you're interested in, and how you want it aggregated (daily, monthly, by business, etc). You can also filter the results to limit it to a certain date range, and to certain business.

    Google Business Profile doesn't provide reliable data for the most recent 5 days.

    You can choose the analytics you want to get among:

    • impressions: desktop maps impressions, mobile maps impressions, desktop search impressions, and mobile search impressions
    • actions: website link clicks, phone calls, and driving directions

    You can use the following filters:

    • by businesses (businesses id in list or not in list)
    • by date (analytics before and/or after a date)
    • by business query. Will return matches for the business name, zipcode or city
    • by business city.

    The response can be aggregated by:

    • business id
    • by date: either by day, week, month or year
    • by both business id and date

    The response can be ordered in ascending or descending order by any of the selected dimensions or metrics. See examples for more details.

    Authorizations:
    ApiKeyAuth
    query Parameters
    metrics
    required
    string
    Enum: "business_impressions_desktop_maps" "business_impressions_desktop_search" "business_impressions_mobile_maps" "business_impressions_mobile_search" "business_direction_requests" "call_clicks" "website_clicks"

    List of analytics to return. At least one in that list.

    dimensions
    string
    Enum: "business" "day" "week" "month" "year"

    How the returned data will be aggregated. At most 'business' and one time dimensions of the list. If no dimension is given, the request will return the sum of each metric for all requested days and businesses.

    order_by
    string
    Enum: "<object>" "-<object>"
    Example: order_by=order_by=-call_clicks

    Where the object is either a dimension or a metric and is used in the request. At most one in the list.

    • before a field to order_by DESC, nothing for ASC
    business__in
    Array of strings (BusinessID)
    Example: business__in=5409c35a97bbc544d8e26737

    Filter by business ids

    business__notin
    Array of strings (BusinessID)
    Example: business__notin=5409c35a97bbc544d8e26737

    Filter by all allowed businesses except the ones given in business__notin

    city
    string

    Filter by city

    query
    string

    Parameter to fuzzy search businesses on city, zipcode and name

    filter_date__gte
    string <datetime>

    Filter by date

    Return all the analytics whose date >= given_date.

    filter_date__lte
    string <datetime>

    Filter by date.

    Return all the analytics whose filter_date <= given_date.

    page
    integer >= 1

    The page number you want to request.

    The value defaults to 1, when it is not included.

    per_page
    integer <= 500

    The maximum number of result items to return in a page.

    The value defaults to 500, when it is not included.

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "page": 1,
    • "count": 1,
    • "max_page": 1,
    • "metrics": [
      ]
    }

    Profile keywords for your business

    This endpoint lets you view the monthly Google Business Profile search keywords for all your businesses subscribed to Presence Management.

    To access the analytics of a business, you need to:

    • have READ access on it
    • have subscribed to Presence Management for this business.
    • You can access the search keywords from Google Business Profile.

    The analytics on search keywords are made available by Google Business Profile on a monthly basis.

    You will receive the following metrics:

    • count: The sum of the number of unique users that used the keyword in a month
    • threshold: A threshold value indicating that the actual value is less than the threshold. Google Business Profile typically displays for search keywords that were used less than 15 times in a month.

    You can use the following filters:

    • by businesses (businesses id in list, and restricted to one business when using the keyword dimension.)
    • by date (analytics before and/or after a date)

    The response can be aggregated by:

    • business id
    • by date: month or year
    • both business id and date

    The response can be ordered by:

    • business id
    • by date: month, or year

    The response can be ordered in ascending or descending order by any of the selected dimensions or metrics.

    Authorizations:
    ApiKeyAuth
    query Parameters
    metrics
    required
    string
    Enum: "count" "threshold"
    Example: metrics=metrics=count,threshold

    List of analytics to return. At least one in that list.

    dimensions
    string
    Enum: "business" "keyword" "month" "year"
    Example: dimensions=dimensions=keyword,month

    How the returned data will be aggregated. At most 'business' and one time dimensions of the list. If no dimension is given, the request will return the sum of each metric for all requested days and businesses.

    order_by
    string
    Enum: "<object>" "-<object>"
    Example: order_by=order_by=-count

    Where the object is either a dimension or a metric and is used in the request. At most one in the list.

    • before a field to order_by DESC, nothing for ASC
    business__in
    Array of strings (BusinessID)
    Example: business__in=5409c35a97bbc544d8e26737

    Filter by business ids

    filter_date__gte
    string <datetime>

    Filter by date.

    Return all the analytics whose date >= given_date.

    filter_date__lte
    string <datetime>

    Filter by date.

    Return all the analytics whose date <= give_date.

    page
    integer >= 1

    The page number you want to request.

    The value defaults to 1, when it is not included.

    per_page
    integer <= 500

    The maximum number of result items to return in a page.

    The value defaults to 500, when it is not included.

    Responses

    Response samples

    Content type
    application/json
    {
    • "page": 1,
    • "count": 1,
    • "max_page": 1,
    • "keywords": [
      ]
    }

    Global reviews statistics

    This endpoint let you view the global reviews statistics for all your businesses subscribed to Review Management.

    You can use the following filters:

    • by date (statistics before and/or after a date)
    • by businesses (businesses id in list or not in list)
    • by keywords

    The response is aggregated according to the previously selected filters.

    In order to get analytics evolution overtime returned by specific time range, please refer to Qualitative Evolution and Quantitative Evolution endpoints.

    Authorizations:
    ApiKeyAuth
    query Parameters
    business__in
    Array of strings (BusinessId)
    Example: business__in=5409c35a97bbc544d8e26737

    Filter by business ids

    Return the reviews of the businesses given in list.

    keywords
    Array of strings
    Example: keywords=bonjour,good+service

    Filter by keywords

    Return all the reviews with not-nullable content, that contain the provided list of keywords.

    Note: This is the content of the review and not the content of the reply.

    The filter accepts both simple and composed words. To indicate it's a composed keyword, add the + as separator. For example:

    keywords=bonjour returns all reviews containing the keyword bonjour

    keywords=good+service returns all reviews containing the combined keyword good service, without splitting the keyword. No reviews containing just good or just service will be returned.

    keywords=bonjour,good+service: returns all reviews that contain either just bonjour, either just good service or both keywords at the same time.

    update_date__gte
    string <datetime>
    Example: update_date__gte=2017-08-01T00:00:00

    Filter by update_date

    Return all the reviews whose update_date >= given_date.

    For example : update_date__gte=2019-01-01T00:00:00 will return all reviews from the first January of 2019 until today.

    Note : The update dates are stored in UTC.

    update_date__lte
    string <datetime>
    Example: update_date__lte=2017-08-02T00:00:00

    Filter by update_date

    Return all the reviews whose update_date <= given_date.

    For example : update_date__lte=2020-01-01T00:00:00 will return all reviews from the date of the first review until the first january of 2020.

    Note : The update dates are stored in UTC.

    Responses

    Response samples

    Content type
    application/json
    {
    • "answer_time": 10493.90997409,
    • "average": 3.0394,
    • "treated": 9,
    • "not_treated": 10,
    • "answered": 8,
    • "satisfied": 10,
    • "neutral": 6,
    • "dissatisfied": 3,
    • "total": 19
    }

    Qualitative evolution

    This endpoint lets you view the qualitative evolution of the reviews rating for all of your businesses subscribed to Review Management. The API returns the reviews average rating by bucket (time range).

    You can use the following filters:

    • by date (analytics before and/or after a date)
    • by businesses (businesses id in list or not in list)
    • by keywords
    Authorizations:
    ApiKeyAuth
    query Parameters
    bucket
    string
    Default: "week"
    Enum: "day" "week" "month" "year"

    Defining the time range of a data bucket.

    This will determine the precision of the returned data. For example, if you choose day, you will receive the number of reviews for each day.

    cumulative
    string
    Default: "true"
    Enum: "true" "false"

    If cumulative = false, return the average rating of reviews from the current bucket only.

    If cumulative = true, return the average rating of reviews from all the buckets until the current one (included). The cumulative representation show the evolution of the average rating over time.

    business__in
    Array of strings (BusinessId)
    Example: business__in=5409c35a97bbc544d8e26737

    Filter by business ids

    Return the reviews of the businesses given in list.

    keywords
    Array of strings
    Example: keywords=bonjour,good+service

    Filter by keywords

    Return all the reviews with not-nullable content, that contain the provided list of keywords.

    Note: This is the content of the review and not the content of the reply.

    The filter accepts both simple and composed words. To indicate it's a composed keyword, add the + as separator. For example:

    keywords=bonjour returns all reviews containing the keyword bonjour

    keywords=good+service returns all reviews containing the combined keyword good service, without splitting the keyword. No reviews containing just good or just service will be returned.

    keywords=bonjour,good+service: returns all reviews that contain either just bonjour, either just good service or both keywords at the same time.

    update_date__gte
    string <datetime>
    Example: update_date__gte=2017-08-01T00:00:00

    Filter by update_date

    Return all the reviews whose update_date >= given_date.

    For example : update_date__gte=2019-01-01T00:00:00 will return all reviews from the first January of 2019 until today.

    Note : The update dates are stored in UTC.

    update_date__lte
    string <datetime>
    Example: update_date__lte=2017-08-02T00:00:00

    Filter by update_date

    Return all the reviews whose update_date <= given_date.

    For example : update_date__lte=2020-01-01T00:00:00 will return all reviews from the date of the first review until the first january of 2020.

    Note : The update dates are stored in UTC.

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      },
    • {
      },
    • {
      }
    ]

    Quantitative evolution

    This endpoint lets you view the quantitative evolution of the number of reviews for all of your businesses subscribed to Review Management. The API returns the cumulative sum of the number of reviews by bucket (time range) selected overtime.

    You can use the following filters:

    • by date (analytics before and/or after a date)
    • by businesses (businesses id in list or not in list)
    • by keywords
    Authorizations:
    ApiKeyAuth
    query Parameters
    bucket
    string
    Default: "week"
    Enum: "day" "week" "month" "year"

    Defining the time range of a data bucket.

    This will determine the precision of the returned data. For example, if you choose day, you will receive the number of reviews for each day.

    business__in
    Array of strings (BusinessId)
    Example: business__in=5409c35a97bbc544d8e26737

    Filter by business ids

    Return the reviews of the businesses given in list.

    keywords
    Array of strings
    Example: keywords=bonjour,good+service

    Filter by keywords

    Return all the reviews with not-nullable content, that contain the provided list of keywords.

    Note: This is the content of the review and not the content of the reply.

    The filter accepts both simple and composed words. To indicate it's a composed keyword, add the + as separator. For example:

    keywords=bonjour returns all reviews containing the keyword bonjour

    keywords=good+service returns all reviews containing the combined keyword good service, without splitting the keyword. No reviews containing just good or just service will be returned.

    keywords=bonjour,good+service: returns all reviews that contain either just bonjour, either just good service or both keywords at the same time.

    update_date__gte
    string <datetime>
    Example: update_date__gte=2017-08-01T00:00:00

    Filter by update_date

    Return all the reviews whose update_date >= given_date.

    For example : update_date__gte=2019-01-01T00:00:00 will return all reviews from the first January of 2019 until today.

    Note : The update dates are stored in UTC.

    update_date__lte
    string <datetime>
    Example: update_date__lte=2017-08-02T00:00:00

    Filter by update_date

    Return all the reviews whose update_date <= given_date.

    For example : update_date__lte=2020-01-01T00:00:00 will return all reviews from the date of the first review until the first january of 2020.

    Note : The update dates are stored in UTC.

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      },
    • {
      },
    • {
      }
    ]

    Review Booster

    All operations related to the Review Booster product.

    ⚠️ SMS send functionality cannot be tested in Sandbox env. All operations related to the Review Booster product.

    ⚠️ SMS send functionality cannot be tested in Sandbox env.

    Send a review invitation

    This endpoint lets you send a SMS to a costumer to help him leave a message on Google. You need to have WRITE access on the business. You can add "invite_content" in your payload to customize the SMS content that will be received by the recipient. Else, the template associated with the user will be used (see /v2/review_booster/template for more info). If no template exist, a new one will be generated.

    Your business needs to be connected to a Google location and to be subscribed to Review Booster product. So this cannot be tested in Sandbox Env. To prevent spamming, a new SMS can be sent to a specific phone number only after 10 days since the last SMS sent.

    Authorizations:
    ApiKeyAuth
    Request Body schema: application/json
    business_id
    required
    string (BusinessId)

    Business id

    target_phone
    required
    string

    Customer phone number, with the country calling code. Eg: +33601020304

    target_name
    string <= 255 characters

    Customer fullname

    template_id
    integer
    Deprecated

    Id of the SMS template you want to use

    invite_content
    string

    To customize SMS content instead of using the SMS template associated with the user. Cannot be used in combination with template_id. @link must be included in your payload (corresponds to the dynamic link that will allow the SMS recipient to leave a review on the business). Max 286 characters (unicode characters are not accepted - will be removed)

    force
    string
    Default: "False"
    Enum: "True" "False"

    To force invitation sending when a SMS has already been sent to the customer

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "business_id": "5409c35a97bbc544d8e26737",
    • "target_phone": "+33647385968",
    • "target_name": "John Doe",
    • "template_id": 31
    }

    Response samples

    Content type
    application/json
    {
    • "invitation_id": "d3d8c966-0356-4ec0-baae-13ec3622ebc2",
    • "status": "success"
    }

    Search for an invitation matching a set of criteria

    This endpoint allows to fetch previously sent invitations. Your access token must be for an user subscribed to the Review Booster product to access this route. The user must have access to the business. This can be useful to avoid sending multiple invitations to the same user in a defined period.

    Authorizations:
    ApiKeyAuth
    query Parameters
    business_id
    required
    string (BusinessId)
    Example: business_id=5409c35a97bbc544d8e26737

    Business id

    target_phone
    required
    string (TargetPhone)
    Example: target_phone=0701020304

    the exact phone number we would have sent the invitation(s) to

    after
    timestamp
    Example: after=1559148288

    Responses

    Response samples

    Content type
    application/json
    {
    • "page": 1,
    • "max_page": 10,
    • "count": 287,
    • "review_invitations": [
      ]
    }

    The status of a review invitation

    This endpoint allows to get the status about an invitation sent through the Review Booster. Your access token must be for a user subscribed to the Review Booster. The invitation id must be for a business for which the user has access to.

    Authorizations:
    ApiKeyAuth
    query Parameters
    invitation_id
    string (InvitationId)
    Example: invitation_id=d3d8c966-0356-4ec0-baae-13ec3622ebc2

    invitation id

    Responses

    Response samples

    Content type
    application/json
    {
    • "invitation_id": "d3d8c966-0356-4ec0-baae-13ec3622ebc2",
    • "status": "CREATED"
    }

    Template for a user

    This endpoint lets you get your corresponding template. If no template exist for the user, a template is created and send back.

    You need to be subscribed to Review Booster product.

    Authorizations:
    ApiKeyAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "template_id": 3462,
    • "template": "Hello ${client_name}, please leave a review ${url}",
    • "status": "success"
    }

    Update the template of a user

    This endpoint lets you update the template associated to the user.

    3 placeholders are available for the template: ${client_name}, ${business_name} and ${url}

    There is 2 mains constraints: ${url} must be present in the template send and the text should not contains more than 250 characters (without placeholders). The template must exist before the request is send.

    You need to be subscribed to Review Booster product.

    Authorizations:
    ApiKeyAuth
    Request Body schema: application/json
    template
    required
    string

    the template content, with placeholder(s) not filled

    Responses

    Request samples

    Content type
    application/json
    {
    • "template": "Hello ${client_name}, please leave a review ${url}"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success"
    }

    Set the expeditor name of a business

    This endpoint lets you set the expeditor name of a business.

    An expeditor name is the name of the sender used to send the message. It will be seen instead of the phone number on the destination phone.

    An expeditor name lenght's must be contain between 3 and 11 characters. No special characters are allowed.

    Your business must be subscribed to Review Booster product.

    Authorizations:
    ApiKeyAuth
    Request Body schema: application/json
    business_id
    required
    string (BusinessId)

    Business id

    expeditor_name
    required
    string

    the new expeditor name

    Responses

    Request samples

    Content type
    application/json
    {
    • "business_id": "5409c35a97bbc544d8e26737",
    • "expeditor_name": "Partoo"
    }

    Response samples

    Content type
    application/json
    {
    • "expeditor_name": "Partoo",
    • "status": "success"
    }

    The expeditor name of a business

    This endpoint lets you get the expeditor name of a business.

    An expeditor name is the name of the sender used to send the message. It will be seen instead of the phone number on the destination phone.

    Your business must be subscribed to Review Booster product.

    Authorizations:
    ApiKeyAuth
    query Parameters
    business_id
    required
    string (BusinessId)
    Example: business_id=5409c35a97bbc544d8e26737

    Business id

    Responses

    Response samples

    Content type
    application/json
    {
    • "expeditor_name": "Partoo",
    • "status": "success"
    }

    Users

    All operations available on users

    Search for users

    This endpoint lets you search for users using filters

    Authorizations:
    ApiKeyAuth
    query Parameters
    email
    string <email>

    Filter by email

    org_id
    integer

    Filter by org id

    query
    string

    To perform a fuzzy search on user

    status
    string (UserStatus)
    Enum: "active" "invited"
    Example: status=active

    Filter users by status

    display_business_ids
    string
    Default: "True"
    Enum: "True" "False"

    The endpoint won’t return the business_ids when the value is False

    page
    integer
    Default: 1

    Page number, Starts at 1. From 1 to 100 results per page (see per_page)

    per_page
    integer [ 1 .. 100 ]
    Default: 30

    Number of items to return per page. Currently limited to 100.

    order_by
    string
    Default: "id"
    Enum: "email" "first_name" "last_name" "role" "org_id" "group_id" "status" "-email" "-first_name" "-last_name" "-role" "-org_id" "-group_id" "-status"

    Order result by given attribute. Reverse order can as well be obtained by using a - (minus sign) before the attribute name, e.g. order_by=-name

    Responses

    Response samples

    Content type
    application/json
    {
    • "page": 1,
    • "max_page": 10,
    • "count": 287,
    • "users": [
      ]
    }

    My user

    This endpoint lets you retrieve all the information about your user

    Authorizations:
    ApiKeyAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "5309c3a237bbc544d8e26737",
    • "org_id": 42,
    • "first_name": "Perceval",
    • "last_name": "de Galles",
    • "email": "perceval@kaamelott.com",
    • "lang": "fr",
    • "phone": "string",
    • "sidebar_products": [
      ],
    • "business_ids": [
      ],
    • "group_id": 42,
    • "accesses": [
      ],
    • "role": "BUSINESS_MANAGER",
    • "provider": "partoo",
    • "status": "active",
    • "keywords": [
      ],
    • "created_at": 1615299414,
    • "shadow_user_id": "",
    • "sso_only": false
    }

    Create user

    This endpoint lets you create a user. If no password given, a password will automatically be generated. The password will be ignored if send_invitation is set to True. You need to have WRITE access on the organisation of the user you want to create.

    Authorizations:
    ApiKeyAuth
    Request Body schema: application/json
    email
    required
    string <email>

    User email (must be unique will return otherwise)

    first_name
    required
    string (UserFirstName)

    User first name

    last_name
    required
    string (UserLastName)

    User last name

    org_id
    integer

    Id of the organisation to which the user should belong. If no org_id given, the user will have the same organisation as you.

    accesses
    array<array<integer>> (accesses)

    List of (list of Group ID).

    Accesses of the users for the new groups system, only for GROUP_MANAGER users.

    See the Groups and Sections description

    business_ids
    Array of strings

    The list of business to which the user has access to. Will be taken into account only if user has BUSINESS_MANAGER role.

    phone
    string (UserPhone)

    User phone number

    role
    string (RoleWithoutProvider)
    Enum: "ORG_ADMIN" "GROUP_MANAGER" "BUSINESS_MANAGER" "PUBLISHER"

    User role in the application

    sidebar_products
    Array of strings (Product)
    Items Enum: "presence_management" "review_booster" "review_management" "messages"
    send_invitation
    string
    Default: "False"
    Enum: "True" "False"

    Send an invitation email to the User

    password
    string <password> (Password) >= 8 characters

    The User password. It should comply with the following rules:

    • should be at least 8 characters long
    • should have one upper case letter and one lower case letter
    • should have one special character
    lang
    string (Lang)
    Enum: "fr" "en" "es" "it" "pt-br" "de" "ar"

    Available language in the application

    sso_only
    boolean (SsoOnly)
    Default: false

    Prevent the user from connecting directly from Partoo connexion page.

    This field is available for users which organization has defined an SSO configuration.

    This field can be edited by a user with role ORG_ADMIN or PROVIDER.

    Responses

    Request samples

    Content type
    application/json
    {
    • "email": "user@example.com",
    • "first_name": "Perceval",
    • "last_name": "de Galles",
    • "org_id": 0,
    • "accesses": [
      ],
    • "business_ids": [
      ],
    • "phone": "string",
    • "role": "BUSINESS_MANAGER",
    • "sidebar_products": [
      ],
    • "send_invitation": "True",
    • "password": "pa$$word",
    • "lang": "fr",
    • "sso_only": false
    }

    Response samples

    Content type
    application/json
    {
    • "id": "5309c3a237bbc544d8e26737",
    • "status": "success"
    }

    User information

    This endpoint lets you retrieve all the information on a user. You need to have READ access to this users.

    Authorizations:
    ApiKeyAuth
    path Parameters
    user_id
    required
    string

    User id

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "5309c3a237bbc544d8e26737",
    • "org_id": 42,
    • "first_name": "Perceval",
    • "last_name": "de Galles",
    • "email": "perceval@kaamelott.com",
    • "lang": "fr",
    • "phone": "string",
    • "sidebar_products": [
      ],
    • "business_ids": [
      ],
    • "group_id": 42,
    • "accesses": [
      ],
    • "role": "BUSINESS_MANAGER",
    • "provider": "partoo",
    • "status": "active",
    • "keywords": [
      ],
    • "created_at": 1615299414,
    • "shadow_user_id": "",
    • "sso_only": false
    }

    Update user

    This endpoint lets you update a user. You need to have WRITE access to this user. It has a patch behaviour which means that only indicated value will be changed.

    Authorizations:
    ApiKeyAuth
    path Parameters
    user_id
    required
    string

    User id

    Request Body schema: application/json
    email
    string <email> (UserEmail)

    User email

    first_name
    string (UserFirstName)

    User first name

    last_name
    string (UserLastName)

    User last name

    org_id
    integer

    Org to which the user should belong

    accesses
    array<array<integer>> (accesses)

    List of (list of Group ID).

    Accesses of the users for the new groups system, only for GROUP_MANAGER users.

    See the Groups and Sections description

    group_id
    integer (GroupId)
    Deprecated

    The id of the group the business belongs to. An organisation can have multiple groups that contain one or more businesses. A business can belong to only one group.

    business_ids
    Array of strings

    The list of business to which the user has access to. Will be taken into account only if user has BUSINESS_MANAGER role.

    phone
    string (UserPhone)

    User phone number

    role
    string (RoleWithoutProvider)
    Enum: "ORG_ADMIN" "GROUP_MANAGER" "BUSINESS_MANAGER" "PUBLISHER"

    User role in the application

    sidebar_products
    Array of strings (Product)
    Items Enum: "presence_management" "review_booster" "review_management" "messages"
    password
    string <password> (Password) >= 8 characters

    The User password. It should comply with the following rules:

    • should be at least 8 characters long
    • should have one upper case letter and one lower case letter
    • should have one special character
    lang
    string (Lang)
    Enum: "fr" "en" "es" "it" "pt-br" "de" "ar"

    Available language in the application

    sso_only
    boolean (SsoOnly)
    Default: false

    Prevent the user from connecting directly from Partoo connexion page.

    This field is available for users which organization has defined an SSO configuration.

    This field can be edited by a user with role ORG_ADMIN or PROVIDER.

    keywords
    Array of strings (Keywords) <= 12 items

    Array of keywords

    receive_reviews_email_notifications
    boolean

    The parameter decides if the user subscribes to negative reviews email notifications

    Responses

    Request samples

    Content type
    application/json
    {
    • "email": "perceval@kaamelott.com",
    • "first_name": "Perceval",
    • "last_name": "de Galles",
    • "org_id": 0,
    • "accesses": [
      ],
    • "group_id": 23,
    • "business_ids": [
      ],
    • "phone": "string",
    • "role": "BUSINESS_MANAGER",
    • "sidebar_products": [
      ],
    • "password": "pa$$word",
    • "lang": "fr",
    • "sso_only": false,
    • "keywords": [
      ],
    • "receive_reviews_email_notifications": true
    }

    Response samples

    Content type
    application/json
    {
    • "id": "5309c3a237bbc544d8e26737",
    • "status": "success"
    }

    Delete user

    This endpoint lets you delete a user. You need to have WRITE access to this user.

    Authorizations:
    ApiKeyAuth
    path Parameters
    user_id
    required
    string

    User id

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "5309c3a237bbc544d8e26737",
    • "status": "success"
    }

    User preferences

    This endpoint lets you retrieve all the information about a user's preferences on notifications. You need to have READ access to this user.

    Authorizations:
    ApiKeyAuth
    path Parameters
    user_id
    required
    string

    User id

    Responses

    Response samples

    Content type
    application/json
    {
    • "reports": {
      },
    • "receive_negative_reviews_email_notifications": true
    }

    Set user preferences

    This endpoint lets you update all the information about a user's preferences on notifications. You need to have WRITE access to this user.

    Authorizations:
    ApiKeyAuth
    path Parameters
    user_id
    required
    string

    User id

    Request Body schema: application/json
    object (UserReports)

    Daily, weekly and monthly reports preferences

    receive_negative_reviews_email_notifications
    boolean (ReceiveNegativeReviewsEmailNotifications)

    Receive a notification when there is a negative review.

    Responses

    Request samples

    Content type
    application/json
    {
    • "reports": {
      },
    • "receive_negative_reviews_email_notifications": true
    }

    Response samples

    Content type
    application/json
    {
    • "id": "5309c3a237bbc544d8e26737",
    • "status": "success"
    }

    Count users

    This endpoint lets you count the users you have READ access to. You can apply filters on this request.

    Authorizations:
    ApiKeyAuth
    query Parameters
    email
    string <email>

    Filter by email

    org_id
    integer

    Filter by organisation id

    status
    string (UserStatus)
    Enum: "active" "invited"
    Example: status=active

    Filter by status

    group_id
    integer
    Deprecated

    Filter by group id

    query
    string

    To perform a fuzzy search on user

    display_business_ids
    string
    Default: "True"
    Enum: "True" "False"

    The endpoint won’t return the business_ids when the value is False

    page
    integer
    Default: 0

    Page number. 30 results per page

    Responses

    Response samples

    Content type
    application/json
    {
    • "count": 287
    }

    Invite user

    This endpoint lets you trigger a new invitation email to an invited user. You need to have WRITE access to this user. The email can only be sent once every 5 minutes.

    Authorizations:
    ApiKeyAuth
    path Parameters
    user_id
    required
    string

    User id

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success"
    }

    User businesses

    This endpoint lets you retrieve the list of businesses which the selected user has READ access to.

    Authorizations:
    ApiKeyAuth
    path Parameters
    user_id
    required
    string

    User id

    Responses

    Response samples

    Content type
    application/json
    {
    • "page": 1,
    • "max_page": 10,
    • "count": 287,
    • "businesses": [
      ]
    }

    Webhooks

    ⚠️ This feature is available only for businesses subscribed to the Messages Product. ⚠️

    The webhooks are a way for you to be automatically notified of real-time events.

    When a specific event occurs, the webhook is triggered and will send you related data through an url that you provided.

    There are two differents types of webhooks:

    • organisation webhook: webhook on the organisation scope, the webhook will trigger for businesses with the same org_id
    • provider webhook: webhook on the provider scope, the webhook will trigger for businesses with the same provider_id

    ⚠️ To activate webhooks, you will need to contact your customer success. ⚠️

    You can subscribe to each event independently.

    To subscribe to an event, you need to provide the following informations:

    • An url where you will receive the event data (can be shared for multiple events)
    • Your org_id or provider_id
    • The type of webhook event you wish to activate (New Message Received, Message Sent Status Update, Message Deleted)

    When an event is triggerd and if you configured a webhook for it, we will make an HTTP Post request to the URL that you provided. The body of the request will contain the payload of the event, as described in the sections below.

    Upon receiving this HTTP request, you must respond with a 200 Success HTTP code.

    If your server fails to treat the incoming request with an Internal error code (500 range), we will assume that the error is temporary and retry sending the event. If after a few attempts the error persists, we will stop retrying and the event will be lost.

    If your server fails with any other error code, we will assume that you cannot treat the request and will not retry sending the event.


    New Business Created Webhook

    This event is triggered when a Business is created in Partoo Database.

    The event payload contains the event type and the business contents

    Responses

    Response samples

    Content type
    application/json
    {
    • "type": "business_created",
    • "payload": {
      }
    }

    Business Updated Webhook

    This event is triggered when a Business is updated in Partoo Database.

    The event payload contains the event type and the business contents.

    Attention, the hook may be triggered on internal changes that may not reflect on the contents sent.

    Responses

    Response samples

    Content type
    application/json
    {
    • "type": "business_updated",
    • "payload": {
      }
    }

    Business Deleted Webhook

    This event is triggered when a Business is removed from Partoo Database.

    The event payload contains the event type and the business id

    Responses

    Response samples

    Content type
    application/json
    {
    • "type": "business_deleted",
    • "payload": {
      }
    }

    New Message Created Webhook

    This event is triggered when a conversation has a new message.

    The event payload contains the event type, the content of the message created, and additional information about the conversation.

    Responses

    Response samples

    Content type
    application/json
    {
    • "type": "message_created",
    • "payload": {
      }
    }

    New message received Deprecated Webhook

    ⚠️ Deprecated, please use the New Message Created webhook instead, and filter on sender_type=Consumer and status=Success to reproduce this webhook comportement.

    This event is triggered when a business receives a new message sent by a Consumer. It is not triggered for messages sent as the business by a User.

    The event payload contains the event type, the content of the message received, and additional information about the conversation.

    Responses

    Response samples

    Content type
    application/json
    {
    • "event": {
      }
    }

    Message sent status update Webhook

    Messages send via Partoo are created with the status Sending, and propagated to the messaging channel. If the message is sent successfully, the status is changed to Success. If the messaging channel fails to send the message, the status changed to Failed. A failed message can be retried using the /retry endpoint.

    This webhook let you know if a message sent has a status change.

    Responses

    Response samples

    Content type
    application/json
    {
    • "event": {
      }
    }

    Message deleted Webhook

    This webhook let you know if a message has been deleted

    Responses

    Response samples

    Content type
    application/json
    {
    • "event": {
      }
    }

    JS SDK

    To know how to integrate Partoo in a white label mode using our JS SDK, please check our JS SDK documentation.

    SSO

    What is SSO ?

    SSO is an authentication method that enables users to access multiple applications with only one set of credentials.

    In the context of Partoo, it is useful for users to access the Partoo app directly from your application directory.

    So there are 2 parts:
    • the Service (the application you connect to, in this case Partoo)
    • the Identity Provider (the provider managing the users and the login, in this case you).
    As a Service, Partoo supports SSO connections as for these 2 protocols managed by the vast majority of Identity Providers (for example Google, Microsoft Azure Active Directory, Okta, etc):
    • SAML
    • OIDC (OpenId Connect) - flow PKCE
    ⚠️ Important: our SSO only allows you to connect to an existing Partoo account; we do not create accounts on the fly via SSO. You will need to create users beforehand via API or via the Partoo interface.

    How to set up SSO with Partoo

    Step 1 - Request an SSO connection

    To set up SSO with Partoo, you will need to contact our technical support team at api@partoo.fr, and precise which protocol you want to use (SAML or OIDC).

    Step 2 - Add a Partoo app to your identity provider

    In the endpoints below, sso_alias is the unique identifier for your SSO, for example "your_enterprise_name". This alias can be modified on demand. You will have to create a Partoo app in your Identity Provider with the following parameters:

    If SAML

    • ACS URL: https://app.partoo.co/api/v2/saml/{sso_alias}/acs
    • Entity Id: https://app.partoo.co/api/v2/saml/{sso_alias}/metadata/
    • Attribute mapping: email => email or urn:oid:0.9.2342.19200300.100.1.3
    • [optional] Allowed callback url: https://app.partoo.co/api/v2/saml/{sso_alias}/acs
    If you need the metadata .xml file for your configuration, you can request it first by mail

    If OIDC

    • redirect URL: https://app.partoo.co/connection?sso_alias={sso_alias}

    Step 3 - Send connection information to Partoo

    Once you have created the app in your Identity Provider, you will need to send the connection information to Partoo. Here what Partoo needs to finalize the configuration:

    If SAML

    • metadata.xml file including, entity id, certificate, and key

    If OIDC

    Your configuration which can include:
    • client_id
    • client_secret
    • your configuration urls (.well_known)

    Step 4 - Test connection

    Once the configuration is done on both side, you can test the login endpoint to initiate the SSO connection:
    • For SAML: https://app.partoo.co/api/v2/saml/{sso_alias}/login
    • For OIDC: https://app.partoo.co/api/v2/oidc/{sso_alias}/login
    You could also log in via SSO from the Partoo connection page.

    FAQ

    How can we create users?

    Users cannot be created automatically with the SSO. They need to be created manually through the app or the API. See API User creation

    How to create an SSO only user?

    To create a user with SSO only, you need to send sso_only = True, send_invitation=False and no password in the creation call.

    What should I do when my certificate expires?

    Your generated certificates have an expiration date. You will be reminded to update them by email (on the technical contact provided) before the certificate expires. You can follow the email instructions, which will ask you to send a new certificate to the given email address.

    Can I use other methods to log in on the connection page?

    Sure, for example, if you use Google as an Identity Provider, you can use the Google login.

    For any other question

    See Technical support