Partoo Rest API (v2)

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 organizations, businesses & users if you are a reseller.
• Retrieve data on businesses you have access to if you are a publisher.
• ...

Upcoming changes

2026-01-15

• Deprecation of phone and keywords fields for users

  The phone and keywords fields in all user-related endpoints (see Users documentation) are now deprecated and will be permanently removed on 2026-01-15.

  Please update your integrations to remove any dependencies on these fields before this date to ensure uninterrupted service. If you currently store data in these fields, we strongly recommend exporting or backing up your data prior to removal.

2025-07-15

• Review analytics V1 API endpoints deprecation

  The impacted endpoints are:

  • GET /v2/reviews/stats
  • GET /v2/reviews/qualitative-evolution
  • GET /v2/reviews/quantitative-evolution

  You can use the new GET /v2/review_analytics/metrics endpoint to get the same data:

  • /v2/reviews/stats ➡ /v2/review_analytics/metrics?metrics=average_rating,rating_distribution,reply_time,reviews_count
    ⚠ The properties treated, not_treated and answer_time are no longer available
    
    
  • /v2/reviews/quantitative-evolution ➡ /v2/review_analytics/metrics?dimensions={dimension}&metrics=reviews_count
    where dimension = day | week | month | year
    
    
  • /v2/reviews/qualitative-evolution ➡ /v2/review_analytics/metrics?dimensions={dimension}&metrics=reviews_count,average_rating
    where dimension = day | week | month | year

• Deprecation of products for features

  We're replacing our products for a new system with features.
  This will allow to have a more fine-grained control over the features available to organizations, businesses and users.
  

  Impacts

  Organization

  You can now retrieve the list of features your org has access to with its subscribed plans through the org_features field.
  You can also retrieve the list of all available features from the org subscribed plans as well as the plans only some businesses may have subscribed to, through the features field.

  Deprecated fields:

  • has_google_post
  • display_google_post

  Business

  You can now retrieve the list of features your business has access to with its organization and its own subscribed plans through the features field. This field does not appear in the GET /v2/business/search endpoint.
  You can now search businesses by features using the features__in and features__notin query parameters.

  User

  We're replacing the sidebar_products field with sidebar_pages field.
  This will allow you to control which pages a user can access to in a more granular way.
  You can find the correspondence between products and features in the table below, this will be used during the transition period.
  ⚠ Warning: during the deprecation time, if you update a user's sidebar_product field and give them presence_management, it will give them the available_features diffusion and presence_analytics.
  ⚠ Warning: during the depreciation time, if you update a user's sidebar_product field with any value, it will give them the posts and bulk_modification features if their organization have the feature.
  ⚠ Warning: during the deprecation time, a user having the product presence_management returned in the sidebar_product field may have only one of the features diffusion and presence_analytics.

  Deprecated field:

  • sidebar_products

  Product	Feature
  presence_management	diffusion and presence_analytics
  review_management	review_management and review_analytics
  review_booster	review_invite
  messages	messages
  Managed at Organization level if the Organization has subscribed to Google Posts	posts
  Managed at Organization level if the Organization has subscribed to Bulk Modification	bulk_modification

  The impacted endpoints are:

  • GET /v2/org/{org_id}
  • GET /v2/org/search
  • GET /v2/user/search
  • GET /v2/user/me
  • GET /v2/user/{user_id}
  • POST /v2/user
  • POST /v2/user/{user_id}
  • GET /v2/business/search
  • GET /v2/business/search/stats
  • GET /v2/business/{business_id}

2025-06-30

• Adding custom channels to messaging

We added a new endpoint:

• POST v2/custom-channels/{channel_id}/messages

We added support for a new channel: Custom. This channel only supports Text content for now.

The impacted endpoints following this change are:

• GET /v2/conversations
• GET /v2/conversations/{conversation_id}
• EVENT message_created
• EVENT message_updated

2025-04-22

• Adding media support to messaging

We added support for 3 new message content_types : Audio, Video and Document.

This means that you will now be able to receive media messages in your conversations, and also send them.

⚠️ Due to channel limitations, some media types are not supported on all channels.

Channel	Image	Video	Audio	Document
Facebook	✅	✅	✅	✅
Instagram	✅	✅	✅	❌
SMS	❌	❌	❌	❌
Whatsapp	✅	✅	✅	✅

This changes will reflect in all endpoints that deal with messages :

• GET /v2/conversations
• GET /v2/conversations/{conversation_id}
• GET /v2/messages
• POST /v2/messages

And message webhooks events :

• EVENT message_created
• EVENT message_updated

2025-02-14

• Webhook configuration API

Customers with access to the webhook feature can now configure their webhooks directly from the API. You can also set webhooks on our website in the settings > integrations > webhooks.

2025-01-15

• Content-Type validation

  Following an upgrade on our webservers, we now enforce a validation of Content-Type on all the requests to avoid guessing. The default value expected is application/json, unless specified on an endpoint. All endpoints with method POST, PATCH and PUT are affected.

• Removing category_gmb_id usage for GmbServices endpoints

  category_gmb_id is definitely removed, use category_gmb_name for the GmbServices endpoints

• Removing Presence analytics endpoints

  Presence analytics endpoints are removed and replaced by Profile metrics and Profile keywords endpoints.

2024-10-15

• Store Code identification

  It is now possible to replace business id by business code as path parameter, only for users inside the same organization. To do so, you may replace /{business_id} by /c-{code}
  

  For example, you can now update a business directly from its code using

  curl -H "x-APIKey: ${API_KEY}" --json '{"address_full": "221b Baker Street"}' https://api.partoo.co/v2/business/c-LON-HQ

  The following endpoints are affected:
  /business/{business_id}
/business/{business_id}/subscription
/business/{business_id}/additional_data
/business/{business_id}/attributes
/business/{business_id}/more_hours
/business/{business_id}/services
/business/{business_id}/services/{service_id}
/business/{business_id}/structured_services
/business/{business_id}/free_form_services
/business/{business_id}/food_menus
/business/{business_id}/place_action_links
/business/{business_id}/business_fields
/publisher_errors/{business_id}


  Explanations

  Since the rate limit has been put in place, it has become harder to integrate our API while complying with this limit. Enabling the search by store code will simplify integrations which required business search just to map our internal ids with codes which are ids in external.

  Why the /c- prefix?
  We believe it is best for an integration to be explicit about requesting with a code rather than an id and we don't want to make guess.

2024-10-15

• Repeatable URL

  Following an update on Google's API, REPEATABLE_URL attributes will no longer be supported. The impacted endpoints are:

  • GET /v2/business/{business_id}/attributes
  • POST /v2/business/{business_id}/attributes

  Replace any usage of REPEATABLE_URL with Place Action Links:

  • GET: /business/{business_id}/place_action_links
  • POST: /business/{business_id}/place_action_links

2024-07-15

• Business address fields are nullable

  Address-related fields within the Business object (address, address_full, address2, zipcode, city, long, lat) can now be null if the business does not have an address filled out.
  The impacted endpoints are :

  • GET /v2/business/search
  • GET /v2/business/{business_id}

• Deprecation of body parameters on DELETE endpoints

  These body parameters are moved to query parameters for these endpoints:

  • DELETE Organization: force

  • DELETE Custom Field: forced_update becomes force

  This route with body parameter is replaced by new route with path parameters:

  • DELETE Google Services with body parameter route is deprecated and replaced with DELETE Google Services with path parameter route

  All these body parameters will be removed on January 15th 2025, please update your integrations by then.

• Renamed forced_update parameter

  The forced_update parameter in the PUT Custom Field endpoint has been renamed to force.

• Webhooks are now signed

  In order to increase security and enable you to verify that incoming traffic comes from Partoo, we have enabled signatures on webhooks. You may find a dedicated section on Webhook Security

2024-06-24

• Swagger Corrections 🎉

  Our Swagger file has been cleaned to make it compliant with standard OpenAPI 3.0.
  No change in API is to expect and no change is required in your existing integrations.
  New integrations can now leverage on tools to automate boilerplate code.

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 organization on API integrations. All organizations will be limited to 300 API calls per minute.

• Presence Analytics Endpoints (DEPRECATION)

  • Google will discontinue its current analytics API endpoint on 20/02/2023 in favour of their new analytics API. The endpoints mentioned below will be deprecated in response to this change.
  • GET /v2/presence_analytics
  • GET /v2/presence_analytics/export
  • 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.
  • GET /v2/posts

2023-04-17

• Messaging Endpoints

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

2023-04-15

• Google Post endpoints (DEPRECATION)

  • Due to the possibility to create Post on Google + Facebook on /posts endpoints. The following endpoint will be deleted :

• Google Services endpoints (BREAKING CHANGES)

  • Changes occurrences of category_gmb_id to category_gmb_name for the GmbServices endpoints in :
    • request body
    • response body
    The following endpoint will be impacted :
  • GET /v2/services/suggestions
  • GET /v2/business/{business_id}/services
  • POST /v2/business/{business_id}/free_form_services
  • POST /v2/business/{business_id}/structured_services

2022-10-15

• Categories endpoints (DEPRECATION)

  • We are changing our categories endpoints to better reflect their use. There are now 2 new parameters for both endpoints :
    • with_names: adds in the return payload the list of translations in each available language
    • with_countries: adds in the return payload the list of countries in which the category is available

  Deprecated endpoint

  • GET /v2/category/{category_id} replaced by GET /v2/categories/{category_id}

  Changed endpoint

  • GET /v2/categories
    • country will not appear in the field names after 2022-10-15
    • The countries list in which a category is available is now in the countries field, use the parameter with_countries
    • names will not appear in the returned payload by default, use the parameter with_names to get it

• Business integration data (DEPRECATION)

  • The following endpoint will be deleted :
  • GET /v2/business/{business_id}/integration_status
  • GET /v2/business/{business_id}/partner_urls

• Presence (DEPRECATION)

  • The following endpoint will be deleted :
  • GET /v2/publisher_states/business_info
  • GET /v2/publisher_states/businesses_info
  • All deleted information are now available on following endpoint :
  • GET /v2/publisher_states

• Review Booster (DEPRECATION)

  • The parameter template_id will be deleted from endpoint :
  • POST /v2/review_booster/send_invitation
  • There will be no impact on template already used by users.

2022-07-15

• Ordering of search results

  • We are aligning our ways of sorting paginated results across all endpoints. All search operations offering ordering now provide a order_by parameter.

  Changed endpoints

  • GET /v2/reviews
  • GET /v2/categories
  • GET /v2/presence_analytics

  Endpoints now providing ordering

  • GET /v2/business/search
  • GET /v2/user/search

• Address details (DEPRECATION)

  • The new field address_full will replace deprecated address_details that will be deleted from July, 2022 :
  • address_full (string) is the new unique address field allowing not to split address in several fields :
    For example : 130 Rue du Mont-Cenis.
  • address_details will be deleted from following endpoints :
  • POST /v2/business
  • GET /v2/business/{business_id}
  • POST /v2/business/{business_id}
  • GET /v2/business/search

  ⚠️ 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.
  • GET /v2/reviews
  • GET /v2/business/search
  • GET /v2/user/search

• API URLs changes (DEPRECATION)

  • Sandbox's API is now accessible at api.sandbox.partoo.co. There is a redirection from sandbox.api.partoo.co to api.sandbox.partoo.co that will be deprecated on January 15th, 2022.

• Address (DEPRECATION)

  • The following endpoints will be deleted on January 15th, 2022:
    • GET /v2/GET street types
    • GET /v2/GET number supplements

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

  • For security reasons, the following routes have been deprecated:
  • POST /v2/authorize
  • GET /v2/authorize/list
  • POST /v2/authorize/revoke
  • If you are still using them, you need to migrate to /v2/connection/generate_token route, which has a similar signature than the deprecated authorization endpoints.

• Business endpoints (UPDATES AND DEPRECATION)

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

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.

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

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"
}

415 - Invalid media type

Our API framework requires Content-Type header to be provided as application/json on POST, PUT and PATCH operations.

If your API integration doesn't properly send this header, an error may appear

{
    "errors": {
        "json": "Unsupported media type. Please use application/json"
    }
}

429 - Too Many Requests

See Rate Limiting

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.

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 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 organizations, businesses, users and groups. If you are a Partoo reseller there will be a provider resource representing you inside Partoo app.
2. Organization: An organization 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 organizations representing your companies. An organization belongs to a provider.
3. User: A user can be a Partoo app user or Partoo API user. A user belongs to an organization 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 organization
5. Group: A group contains businesses, each organization 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 organization.

For now there are 5 roles available:

• PROVIDER role is meant for reseller admin user. It can manage organizations, users and businesses of a provider
• ORG_ADMIN role is meant for client admin user. It can manage the user and businesses of its organization
• 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 organizations, users and businesses.

Read access

Write access

ORG_ADMIN

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

Read access

Write access

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

Write access

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

Write access

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

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

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.

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

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