When dealing with media messages (`Image`, `Video`, `Audio`,
`Document`), there are some
additionnal file type and file size limitations.
- Image size should not exceed 5 MB.
- Video size should not exceed 16 MB.
- Audio size should not exceed 16 MB.
- Document size should not exceed 100 MB.
For optimal support, you should target the following file types :
- Image : `jpeg`, `png`.
- Video : `mp4`.
- Audio : `aac`, `mp4`.
- Document : `xls`, `xlsx`, `docx`, `pdf`, `ppt`, `pptx`.
A successful HTTP response to this endpoint (code 200) does not
necessarily mean that the
message has been correctly delivered to the consumer, only that it has
been created on
Partoo.
To ensure that the message has been delivered successfully, we recommend
subscribing to the
[Message Updated](/api-reference/webhooks-events/message-updated)
Webhook, and checking that the `status` field
of the message has switched to `Success`.
If the answer has failed to be sent, you can send it again by using the
[/retry endpoint](/api-reference/messages/retry-send-message)
requestBody:
required: true
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/PostTextMessage'
- $ref: '#/components/schemas/PostImageUrlMessage'
- $ref: '#/components/schemas/PostAudioMessage'
- $ref: '#/components/schemas/PostVideoMessage'
- $ref: '#/components/schemas/PostDocumentMessage'
multipart/form-data:
schema:
$ref: '#/components/schemas/PostImageMessage'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- success
message_id:
type: integer
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/messages/{message_id}/retry:
post:
operationId: retrySendMessage
tags:
- Messages
summary: Retry send message
description: >
This endpoint let you retry sending a message that has failed to be
sent.
parameters:
- name: message_id
in: path
schema:
type: integer
description: The id of the message to send
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- success
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
/custom-channels/{channel_id}/messages:
post:
tags:
- Custom Channels
summary: Ingest message
operationId: customChannelMessages
description: >
This endpoint lets you ingest messages in conversations that use custom
channels. When called, it creates a new message in the specified
conversation. If the conversation does not exist, the endpoint will
automatically create the conversation before adding the message.
You must use an API key with `ORG_ADMIN` or `PROVIDER` rights for this
endpoint.
⚠️ A `200 OK` response does not guarantee that the message was
successfully created.
It only means the request was received and accepted for processing. ⚠️
parameters:
- name: channel_id
in: path
required: true
schema:
type: string
description: The id of the custom channel
requestBody:
required: true
content:
application/json:
schema:
description: Request body to ingest a new message in a conversation
type: object
required:
- business_id
- external_conversation_id
- external_message_id
- content
- sender_type
properties:
business_id:
type: string
description: The id of the business.
external_conversation_id:
type: string
description: >-
The unique id of the conversation in your system. Messages
with the same `external_conversation_id` & `channel_id` will
be grouped within the same Partoo Conversation.
external_message_id:
type: string
description: >-
The unique id of the message in your system. Messages with
the same `external_message_id` & `channel_id` will be
considered as duplicates and will be ignored.
content:
type: string
description: The message content.
sender_type:
type: string
enum:
- User
- Consumer
consumer_name:
type:
- string
- 'null'
default: 'null'
description: >-
Display name of the consumer. This property is only used at
the creation of the conversation.
consumer_image:
type:
- string
- 'null'
default: 'null'
description: >-
Profile image URL of the consumer. This property is only
used at the creation of the conversation.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- success
'403':
$ref: '#/components/responses/403'
/messaging/templates:
get:
operationId: listMessageTemplates
tags:
- Message Reply Templates
summary: List message templates
description: >
This endpoint retrieves the list of message templates for the current
user's organization.
responses:
'200':
description: A list of message templates
content:
application/json:
schema:
type: array
description: The list of message reply templates.
items:
$ref: '#/components/schemas/MessageReplyTemplate'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
post:
operationId: createMessageTemplates
tags:
- Message Reply Templates
summary: Create message template
description: >
This endpoint lets you create a new message template.
⚠️ The content should be a valid __stringified JSON__ object. It has to
include both the `"text"` key with the message content
and the pair `"_version": "0.1"`.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MessageTemplateCreateRequest'
responses:
'200':
description: The message template created
content:
application/json:
schema:
$ref: '#/components/schemas/MessageReplyTemplate'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/messaging/templates/{template_id}:
put:
operationId: updateTemplate
tags:
- Message Reply Templates
summary: Update message template
description: |
This endpoint allows updating an existing message template by its ID.
parameters:
- $ref: '#/components/parameters/path_template_id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MessageTemplateUpdateRequest'
responses:
'200':
description: The message template created
content:
application/json:
schema:
$ref: '#/components/schemas/MessageReplyTemplate'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
delete:
operationId: deleteMessageTemplate
tags:
- Message Reply Templates
summary: Delete message template
description: |
This endpoint lets you delete a message template given its ID.
parameters:
- $ref: '#/components/parameters/path_template_id'
responses:
'200':
description: Template deleted successfully
content:
application/json:
schema:
type: boolean
example: true
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/messaging/settings:
get:
operationId: settings
tags:
- Messaging Settings
summary: List messaging settings
description: >
This endpoint lets you list all the Messaging Settings you have access
to.
You can filter the Messaging Settings based on the Organization or the
Business that they are related to.
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
- $ref: '#/components/parameters/query_business__in'
responses:
'200':
description: OK
content:
application/json:
schema:
description: Response object
type: object
properties:
settings:
type: array
description: The list of Messaging Settings, paginated.
items:
$ref: '#/components/schemas/MessagingSetting'
page:
$ref: '#/components/schemas/Page'
count:
$ref: '#/components/schemas/Count'
max_page:
$ref: '#/components/schemas/MaxPage'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/messaging/settings/{setting_id}:
post:
tags:
- Messaging Settings
summary: Update messaging settings
operationId: updateMessagingSettings
description: |
This endpoint lets you update a specific Messaging Settings.
parameters:
- name: setting_id
in: path
required: true
schema:
type: integer
description: The id of the Messaging Settings to update
requestBody:
required: true
content:
application/json:
schema:
description: Request body to update a Post
type: object
properties:
welcome_message:
$ref: '#/components/schemas/MessagingSettingWelcomeMessage'
offline_message:
$ref: '#/components/schemas/MessagingSettingOfflineMessage'
uses_business_hours:
$ref: '#/components/schemas/MessagingSettingUsesBusinessHours'
custom_chat_hours:
$ref: '#/components/schemas/ChatHours'
is_launched:
$ref: '#/components/schemas/MessagingSettingIsLaunched'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MessagingSetting'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/custom_fields:
get:
tags:
- Custom Fields
summary: Get custom fields
description: >
This endpoint enables you to get custom fields for your organization,
including their names, descriptions, types, constraints, section
associations, and slugs.
operationId: getCustomFields
parameters:
- $ref: '#/components/parameters/query_filter_by_org_id'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
custom_fields:
type: array
items:
$ref: '#/components/schemas/CustomFieldTypeGet'
example:
custom_fields:
- id: 1
name: Is Active
description: Whether the business is currently active
type: BOOLEAN
order: 1
section_id: null
section_name: null
slug: is-active
- id: 2
name: Description
description: Business description text
type: TEXT
max_len: 500
order: 2
section_id: 1
section_name: Section 1
slug: description
- id: 3
name: Employee Count
description: Number of employees
type: INTEGER
min: 0
max: 10000
order: 3
section_id: 1
section_name: Section 1
slug: employee-count
- id: 4
name: Rating
description: Business rating score
type: FLOAT
min: 0
max: 5
order: 4
section_id: 2
section_name: Section 2
slug: rating
- id: 5
name: Category
description: Business category type
type: SINGLE_SELECT
possible_values:
- Premium
- Standard
- Basic
order: 5
section_id: 2
section_name: Section 2
slug: category
- id: 6
name: Tags
description: Business tags for classification
type: MULTIPLE_SELECT
possible_values:
- Featured
- New
- Sale
- Popular
max_selected_values: 3
order: 6
section_id: 3
section_name: Section 3
slug: tags
- id: 7
name: Product Images
description: Product image selections
type: MULTIPLE_SELECT_IMAGE
possible_values:
- image1
- image2
- image3
possible_images_urls:
- https://example.com/img1.jpg
- https://example.com/img2.jpg
- https://example.com/img3.jpg
possible_images_labels:
- Image 1
- Image 2
- Image 3
max_selected_values: 2
order: 7
section_id: 3
section_name: Section 3
slug: product-images
- id: 8
name: Gallery
description: Image gallery uploader
type: IMAGES_UPLOADER
text_fields:
- text_field: Caption
max_length: 100
- text_field: Alt Text
max_length: 50
order: 8
section_id: 4
section_name: Section 4
slug: gallery
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
post:
tags:
- Custom Fields
summary: Create custom fields
description: >
This endpoint enables you to create custom fields for your organization.
You can specify the field name, description, slug, type-specific
constraints, order, and optionally assign it to a section. `PROVIDER`
users can pass `org_id` to create custom fields for a managed
organization.
operationId: postCreateCustomFields
parameters:
- $ref: '#/components/parameters/query_org_id'
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- title: Boolean Field
$ref: '#/components/schemas/CustomFieldBool'
- title: Text Field
$ref: '#/components/schemas/CustomFieldText'
- title: Integer Field
$ref: '#/components/schemas/CustomFieldInteger'
- title: Float Field
$ref: '#/components/schemas/CustomFieldFloat'
- title: Single Select Field
$ref: '#/components/schemas/CustomFieldSingleSelect'
- title: Multiple Select Field
$ref: '#/components/schemas/CustomFieldMultipleSelect'
- title: Multiple Select Image Field
$ref: '#/components/schemas/CustomFieldMultipleSelectImage'
- title: Images Uploader Field
$ref: '#/components/schemas/CustomFieldImagesUploader'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
custom_field_id:
$ref: '#/components/schemas/CustomFieldId'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/custom_fields/{custom_field_id}:
put:
tags:
- Custom Fields
summary: Update custom field
description: >
This endpoint enables you to update a specific custom field of your
organization by specifying its ID.
You can update the **name**, **description**, **slug**, **constraints**,
and **section assignment** of the custom field. However, the **type** of
a custom field cannot be modified. Use the `force` parameter to apply
changes that might conflict with existing business data. `PROVIDER`
users can pass `org_id` to update a custom field for a managed
organization.
operationId: putUpdateCustomFields
parameters:
- $ref: '#/components/parameters/custom_field_id'
- $ref: '#/components/parameters/query_org_id'
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- title: Boolean Field
$ref: '#/components/schemas/CustomFieldEditTypeBool'
- title: Text Field
$ref: '#/components/schemas/CustomFieldEditTypeText'
- title: Integer Field
$ref: '#/components/schemas/CustomFieldEditTypeInteger'
- title: Float Field
$ref: '#/components/schemas/CustomFieldEditTypeFloat'
- title: Single Select Field
$ref: '#/components/schemas/CustomFieldTypeEditSingleSelect'
- title: Multiple Select Field
$ref: '#/components/schemas/CustomFieldTypeEditMultipleSelect'
- title: Multiple Select Image Field
$ref: '#/components/schemas/CustomFieldTypeEditMultipleSelectImage'
- title: Images Uploader Field
$ref: '#/components/schemas/CustomFieldTypeEditImagesUploader'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/RequestStatus'
'400':
description: New constraints are not respected for some businesses
content:
application/json:
schema:
anyOf:
- title: Text Field Error
type: object
properties:
errors:
type: object
properties:
json:
type: object
properties:
businesses_count:
type: integer
description: Number of businesses in error
example: 2
description:
type: string
description: Error description
example: >-
At least one business does not respect the new
constraints, please send forced_update=true to
force update.
constraints:
type: array
description: Constraints in error
items:
type: string
example:
- max_len
- title: Number Field Error
type: object
properties:
errors:
type: object
properties:
json:
type: object
properties:
businesses_count:
type: integer
description: Number of businesses in error
example: 2
description:
type: string
description: Error description
example: >-
At least one business does not respect the new
constraints, please send forced_update=true to
force update.
constraints:
type: array
description: Constraints in error
items:
type: string
example:
- min
- max
- title: Select Field Error
type: object
properties:
errors:
type: object
properties:
json:
type: object
properties:
businesses_count:
type: integer
description: Number of businesses in error
example: 2
description:
type: string
description: Error description
example: >-
At least one business had one of these values,
please send forced_update=true to force
update.
options:
type: array
description: Options in error
items:
type: string
example:
- free parking
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
delete:
tags:
- Custom Fields
summary: Delete custom field
description: >
This endpoint enables you to delete a specific custom field of your
organization by specifying its ID. Use the `force` parameter to delete
fields that have values assigned to businesses. `PROVIDER` users can
pass `org_id` to delete a custom field for a managed organization.
operationId: deleteCustomFields
parameters:
- $ref: '#/components/parameters/custom_field_id'
- $ref: '#/components/parameters/query_org_id'
- name: force
in: query
required: false
schema:
type: boolean
description: >-
If true, destructive modification will be performed and businesses
values will be deleted accordingly
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/RequestStatus'
'400':
description: Custom field value is defined for a business
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
json:
type: object
properties:
businesses_count:
type: integer
description: Number of businesses in error
example: 2
description:
type: string
description: Error description
example: >-
At least one business has this custom field,
please send forced_update=true to force update.
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/custom_fields/order:
post:
tags:
- Custom Fields
summary: Order custom fields
description: >
This endpoint enables you to reorganize the order of custom fields and
custom field sections within your organization. You can also move custom
fields between sections by specifying a different section_id. `PROVIDER`
users can pass `org_id` to reorder custom fields for a managed
organization.
operationId: postOrderCustomFields
parameters:
- $ref: '#/components/parameters/query_org_id'
requestBody:
required: true
content:
application/json:
schema:
description: Request object to reorder custom fields and optionally sections
type: object
required:
- orders
properties:
orders:
$ref: '#/components/schemas/CustomFieldOrders'
section_orders:
$ref: '#/components/schemas/CustomFieldSectionOrders'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/RequestStatus'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/custom_fields/section:
get:
tags:
- Custom Fields Section
summary: Get custom field sections
description: >
Retrieve list of custom fields sections for a given organization,
including their names, descriptions, slugs, and ordering information.
operationId: getCustomFieldsSection
parameters:
- $ref: '#/components/parameters/query_filter_by_org_id'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
sections:
type: array
items:
type: object
properties:
id:
$ref: '#/components/schemas/CustomFieldSectionId'
name:
$ref: '#/components/schemas/CustomFieldSectionName'
description:
$ref: '#/components/schemas/CustomFieldSectionDescription'
order:
$ref: '#/components/schemas/CustomFieldSectionOrder'
slug:
$ref: '#/components/schemas/CustomFieldSectionSlug'
example:
- id: 1
name: Section A
description: Primary information section
order: 3
slug: section-a
- id: 2
name: Section B
description: null
order: 4
slug: section-b
- id: 3
name: Section C
description: Additional details section
order: 5
slug: null
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
post:
tags:
- Custom Fields Section
summary: Create custom field sections
description: >
This endpoint enables you to create custom field sections for your
organization. You can specify a name, optional description, slug, and
order. If no order is provided, it will be set to max(all current
sections orders) + 1. `PROVIDER` users can pass `org_id` to create
custom field sections for a managed organization.
operationId: postCustomFieldsSection
parameters:
- $ref: '#/components/parameters/query_org_id'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
$ref: '#/components/schemas/CustomFieldSectionName'
description:
$ref: '#/components/schemas/CustomFieldSectionDescription'
slug:
$ref: '#/components/schemas/CustomFieldSectionSlug'
order:
$ref: '#/components/schemas/CustomFieldSectionOrder'
example:
name: Primary Information
description: Contains essential business details
order: 1
slug: primary-info
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
section_id:
$ref: '#/components/schemas/CustomFieldSectionId'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/custom_fields/section/{section_id}:
put:
tags:
- Custom Fields Section
summary: Update custom field sections
description: >
This endpoint enables you to update a specific custom field section of
their organization. You can update the name, description, and slug of
the section. `PROVIDER` users can pass `org_id` to update custom field
sections for a managed organization.
operationId: putCustomFieldsSection
parameters:
- $ref: '#/components/parameters/section_id'
- $ref: '#/components/parameters/query_org_id'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
$ref: '#/components/schemas/CustomFieldSectionName'
description:
$ref: '#/components/schemas/CustomFieldSectionDescription'
slug:
$ref: '#/components/schemas/CustomFieldSectionSlug'
example:
name: Updated Section Name
description: Updated description for the section
slug: updated-section-slug
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/RequestStatus'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
delete:
tags:
- Custom Fields Section
summary: Delete custom field section
description: >
This endpoint enables you to delete a specific custom field section of
your organization. All custom fields in the section will be moved to no
section (section_id = null). `PROVIDER` users can pass `org_id` to
delete custom field sections for a managed organization.
operationId: deleteCustomFieldsSection
parameters:
- $ref: '#/components/parameters/section_id'
- $ref: '#/components/parameters/query_org_id'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/RequestStatus'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/custom_role:
get:
operationId: customRoles
tags:
- Custom Roles
summary: List Custom Roles
description: |
Get all Custom Roles for your organization.
parameters:
- $ref: '#/components/parameters/query_page'
- $ref: '#/components/parameters/query_per_page_1_100'
- $ref: '#/components/parameters/query_org_id'
- name: only_available_roles
in: query
description: >
If `true`: only return roles for which the requesting user has *all*
required permissions (Custom Fields permissions are also taken into
account).
required: false
schema:
type: boolean
default: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CustomRoleGetResponse'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
post:
tags:
- Custom Roles
summary: Create Custom Role
description: >
This endpoint enables you to create custom roles for organizations
within your scope.
operationId: createCustomRole
parameters:
- $ref: '#/components/parameters/query_org_id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomRoleCreationBody'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CustomRoleCreationResponse'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/custom_role/{custom_role_api_id}:
get:
tags:
- Custom Roles
summary: Get Custom Role
description: |
Get the details of a specific Custom Role.
operationId: getCustomRoleDetail
parameters:
- $ref: '#/components/parameters/query_org_id'
- $ref: '#/components/parameters/path_custom_role_api_id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CustomRoleDetail'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
post:
tags:
- Custom Roles
summary: Update Custom Role
description: >
Update a Custom Role, allowing you to set the `name`, `api_id`,
`description`, and `permissions` of an already existing Custom Role.
operationId: updateCustomRole
parameters:
- $ref: '#/components/parameters/query_org_id'
- $ref: '#/components/parameters/path_custom_role_api_id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomRoleUpdateBody'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CustomRoleUpdateResponse'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
delete:
tags:
- Custom Roles
summary: Delete Custom Role
description: >
This endpoint enables you to delete custom roles for organizations
within your scope.
operationId: deleteCustomRole
parameters:
- $ref: '#/components/parameters/query_org_id'
- $ref: '#/components/parameters/path_custom_role_api_id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CustomRoleDeletionResponse'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/custom_role/duplicate:
post:
tags:
- Custom Roles
summary: Duplicate Custom Role
description: >
Duplicate a Custom Role.
A new Custom Role with (almost) the same `name` and `api_id`, and
identical `description` and `permissions` will be created in your
organization.
The new `name` will be the same as the original role, with an added
suffix
- `"My Custom Role"` → `"My Custom Role - 2"`
And similar for the `api_id`:
- `"my_custom_role"` → `"my_custom_role_2"`
operationId: duplicateCustomRole
parameters:
- $ref: '#/components/parameters/query_org_id'
- $ref: '#/components/parameters/path_custom_role_api_id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CustomRoleDuplicateResponse'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/permissions:
get:
tags:
- Custom Roles
summary: Get Permissions
description: >
This endpoint will give you all of the permissions available to your
organization. The permissions are categorized by section, and by
subsection. The permissions available to your organization are based on
the plans your organization subscribes to; and thus the features
included in those plans.
operationId: getPermissions
parameters:
- $ref: '#/components/parameters/query_org_id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Permissions.GetSuccessResponse'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/org/{org_id}/switch_to_custom_roles:
get:
summary: Get Custom Roles switch status
description: >
Get the current status of the organization's switch to Custom Roles.
This endpoint returns information about whether the organization has
switched to Custom Roles and whether they are allowed to switch.
operationId: getSwitchToCustomRoles
tags:
- Custom Roles
parameters:
- $ref: '#/components/parameters/path_org_id'
responses:
'200':
description: Successfully retrieved switch status
content:
application/json:
schema:
type: object
properties:
org_id:
$ref: '#/components/schemas/OrgId'
has_switched:
type: boolean
description: Whether the organization has switched to Custom Roles
example: true
can_switch:
type: boolean
description: >-
Whether the organization is allowed to switch to Custom
Roles
example: false
required:
- org_id
- has_switched
- can_switch
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
post:
summary: Switch to Custom Roles
description: >
Update the organization's Custom Roles switch status.
This endpoint allows you to enable or disable the Custom Roles feature
for the organization, provided the organization is allowed to make this
change.
operationId: switchCustomRoles
tags:
- Custom Roles
parameters:
- $ref: '#/components/parameters/path_org_id'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- switch_to_custom_roles
properties:
switch_to_custom_roles:
type: boolean
description: >-
Whether to switch to Custom Roles (true) or revert to
standard roles (false)
example: true
responses:
'200':
description: Successfully updated Custom Roles switch status
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- success
description: Request status
example: success
org_id:
type: integer
description: >
Unique identifier for the organization you want to switch.
Only `PROVIDER` users can use this field. If you are not a
`PROVIDER`, this will default to the ID of your
organization.
example: 123
required:
- status
- org_id
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
description: >
You are not allowed to switch your organization to the new Custom
Roles system.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
example: You are not allowed to switch
'404':
$ref: '#/components/responses/404'
/attributes/list:
get:
summary: List Google Attributes
description: >
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](/api-reference/businesses/google-attributes-for-your-business).
To handle attributes values for businesses, [see set attributes business
endpoints](/api-reference/businesses/set-google-attributes-for-your-business).
This endpoint allows you to view the **Google** attributes available for
a given Category.
operationId: getAttributes
tags:
- Google
parameters:
- $ref: '#/components/parameters/category_name'
- $ref: '#/components/parameters/country'
- $ref: '#/components/parameters/lang'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AttributesGroupResponse'
'400':
description: Wrong or missing parameters
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/AttributesMissingParametersError'
- $ref: '#/components/schemas/AttributesWrongCategoryError'
- $ref: '#/components/schemas/AttributesWrongLangError'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/more_hours/list:
get:
summary: List Google more hours
description: >
⚠️ **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](/api-reference/businesses/more-hours-for-your-business).
To handle More Hours for businesses, see [Update More Hours for your
Business
endpoints](/api-reference/businesses/set-more-hours-for-your-business).
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.
operationId: moreHours
tags:
- Google
parameters:
- $ref: '#/components/parameters/category_more_hours_list'
- $ref: '#/components/parameters/country_more_hours_list'
- $ref: '#/components/parameters/lang_more_hours'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MoreHoursListResponse'
'400':
description: Wrong or missing parameters
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/MoreHoursListMissingParametersError'
- $ref: '#/components/schemas/MoreHoursListInvalidCategoryError'
- $ref: '#/components/schemas/MoreHoursListInvalidCountryError'
- $ref: '#/components/schemas/AttributesWrongLangError'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/lodging/list:
get:
summary: List Google Lodging attributes
description: >
Get all Google Lodging attributes available in Partoo.
Google Lodging attributes describe hotel-specific information such as
property features, services, policies, amenities, and guest unit
details.
The response is grouped by lodging section. Each attribute definition
gives the Google attribute id, its type, display order, available enum
options when relevant, whether an exception code can be used instead of
a value, and whether the attribute is read-only.
Attributes marked with `read_only: true` are returned for display
purposes only and cannot be modified through `POST
/v2/business/{business_id}/lodging`.
operationId: getLodgingList
tags:
- Google
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LodgingListResponse'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/services/suggestions:
get:
summary: List Google Services
description: >
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 satisfied with those? You can add your very own custom services and
link them to the category of your business of your choice!
To recover service values set for a business, see [get services business
endpoints](/api-reference/businesses/google-services-for-your-business).
To handle service values for businesses, see [set structured services
business
endpoints](/api-reference/businesses/set-google-attributes-for-your-business).
To handle custom service values for businesses, see [set free form
services business
endpoints](/api-reference/businesses/set-custom-google-services-for-your-business).
This endpoint allows you to view the Google Services available for your
business.
The services available depend on the categories of the business, not
only the main one.
operationId: getServicesSuggestions
tags:
- Google
parameters:
- $ref: '#/components/parameters/query_business__in'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ServicesSuggestionResponse'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/google-oauth-accounts/locations/{google_location_id}:
get:
summary: Details on a specific Google Location
description: >
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.
operationId: getGoogleLocation
tags:
- Google
parameters:
- $ref: '#/components/parameters/google_location_id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleLocation'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/google-oauth-accounts/locations/search:
get:
summary: Search for Google locations
description: >
Performs a search for Google locations based on the provided query
parameters. This endpoint requires authentication, and only authorized
users with the appropriate permissions can access it.
operationId: searchGoogleLocations
tags:
- Google
parameters:
- name: query
in: query
description: >
The search query string. It searches on the following fields of the
Google location:
- `locality` (e.g., https://api.partoo.co/v2/google-oauth-accounts/locations/search?query=Paris)
- `postal_code` (e.g., https://api.partoo.co/v2/google-oauth-accounts/locations/search?query=75018)
- `location_name` (e.g., https://api.partoo.co/v2/google-oauth-accounts/locations/search?query=Annie%20-%20HQ)
- `address_details` (e.g., https://api.partoo.co/v2/google-oauth-accounts/locations/search?query=130%20rue%20mont%20cenis)
- `store_code` (e.g., https://api.partoo.co/v2/google-oauth-accounts/locations/search?query=annie-hq)
required: false
schema:
type: string
- name: google_location_id
in: query
description: The ID of the Google location stored in Partoo.
required: false
schema:
type: string
- name: oauth_account_id
in: query
description: The ID of the OAuth account stored in Partoo.
required: false
schema:
type: string
- name: not_connected_only
in: query
description: Filter for locations not connected to any business.
required: false
schema:
type: boolean
- name: verification_status
in: query
description: Filter by verification status.
required: false
schema:
type: string
- name: page
in: query
description: The page number for pagination.
required: false
schema:
type: integer
default: 1
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleLocations'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/verifications/google-locations/{google_location_id}/options:
get:
summary: Fetch Google Location Verification Options
description: >
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.
operationId: fetchGoogleLocationVerificationOptions
tags:
- Google
parameters:
- $ref: '#/components/parameters/google_location_id'
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
status:
description: >-
The status of the response `success`, `warning` or
`error`.
type: string
example: success
options:
description: List of available verification options returned.
type: array
items:
type: object
properties:
method:
type: string
description: >-
The method of verification, can be `PHONE_CALL`,
`SMS`, `EMAIL` or `ADDRESS`.
example: PHONE_CALL
phone_number:
type: string
description: >
*OPTIONAL* Depending on the status:
- `AVAILABLE`: The phone number to which the code will be sent, either through an automated call or a text message.
- `PENDING`: The phone number where the code has been sent in case of `PENDING` status.
Note that this attribute is only returned for
`PHONE_CALL` and `SMS` methods.
example: '+33187662490'
email:
type: string
description: >
*OPTIONAL* The email address to which the code will
be or has been sent. Note that this attribute is
only returned for `EMAIL` method.
example: email.api@partoo.fr
full_name:
type: string
description: >
**OPTIONAL and only with `PENDING` status:** The
full name to which the postcard has been sent to.
Note that this attribute is only returned for
`ADDRESS` method.
example: John Doe
full_address:
type: string
description: >
*OPTIONAL* The full address to which the postcard
will be or has been sent to. Note that this
attribute is only returned for `ADDRESS` method.
example: 190 Rue Championnet, 75018 Paris
expected_delivery_days:
type: integer
description: >
*OPTIONAL* The expected of business days it will
take for the postcard to be delivered. Note that
this attribute is only returned for `ADDRESS`
method.
example: 2
status:
type: string
description: >-
The status of the verification option, can be
`PENDING` or `AVAILABLE`.
example: AVAILABLE
message:
type: string
description: >
*OPTIONAL* Details of the message. Can be one of the
following:
- `listing_verified`: The location is already verified (returned with a `success` status).
- `listing_in_review`: The location is already in review for verification (returned with a `warning` status).
- `listing_disabled`: The location is disabled (returned with a `error` status).
- `listing_suspended`: The location is suspended (returned with a `error` status).
- `listing_status_not_found`: The location is not found (returned with a `error` status).
example: null
enum:
- listing_verified
- listing_in_review
- listing_disabled
- listing_suspended
- listing_status_not_found
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/verifications/google-locations/{google_location_id}/start:
post:
summary: Start Google Location Verification Process
description: >
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.
operationId: startGoogleLocationVerification
tags:
- Google
parameters:
- $ref: '#/components/parameters/google_location_id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
method:
type: string
enum:
- SMS
- PHONE_CALL
- EMAIL
- ADDRESS
phone_number:
type: string
description: >
**REQUIRED** for `SMS` and `PHONE_CALL` methods. The phone
number to which the code will be send.
example: '+33187662490'
email:
type: string
description: >
**REQUIRED** for `EMAIL` method. The email address to which
the code will be send.
example: email.api@partoo.fr
full_name:
type: string
description: >
**REQUIRED** for `ADDRESS` method. The full name to which
the postcard will be send.
example: John Doe
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: The status of the response `success` or `error`.
example: success
message:
type: string
example: null
description: >
*OPTIONAL* Details of the error encountered. Can be one of
the following:
- `start_no_verification_found`: No verification request has been started.
- `start_error`: An error occured during the start of the verification process.
enum:
- start_no_verification_found
- start_error
'400':
description: Your request is incorrect
content:
application/json:
schema:
description: |
Error that occcurs when your request is incorrect
properties:
errors:
type: object
description: The detail of the error encountered.
properties:
json:
type: object
properties:
method:
type: string
description: >
Details of the error encountered. Can be one of
the following:
- `sms_phone_call_method_without_phone_number`: The phone number is required for `SMS` and `PHONE_CALL` methods.
- `email_method_without_email`: The email address is required for `EMAIL` method.
- `address_method_without_full_name`: The full name is required for `ADDRESS` method.
- `not_supported`: The method is not supported.
example: sms_phone_call_method_without_phone_number
enum:
- sms_phone_call_method_without_phone_number
- email_method_without_email
- address_method_without_full_name
- not_supported
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/verifications/google-locations/{google_location_id}/complete:
post:
summary: Complete Google Location Verification Process
description: >
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.
operationId: completeGoogleLocationVerification
tags:
- Google
parameters:
- $ref: '#/components/parameters/google_location_id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
method:
type: string
enum:
- PHONE_CALL
- SMS
- EMAIL
- ADDRESS
pin_code:
type: string
description: >-
The PIN code provided by the user during the verification
process.
example: '1234'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: The status of the response `success` or `error`.
example: success
message:
type: string
example: null
description: |
Details of the message. Can be one of the following:
- `complete_success`: The verification process has been completed successfully (returned with a `success` status).
- `complete_in_review`: The verification process has been completed successfully but the verification is still in review (returned with a `success` status).
- `complete_only_pending`: The verification process can be completed only on a `PENDING` verification (returned with a `error` status).
- `complete_invalid_pin`: The PIN code provided is invalid (returned with a `error` status).
- `complete_error`: An error occurred during the completion of the verification process (returned with a `error` status).
enum:
- complete_success
- complete_in_review
- complete_only_pending
- complete_invalid_pin
- complete_error
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/sections:
post:
tags:
- Groups and Sections
operationId: createGroupSection
summary: Create Section
description: >
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
group system, see [the Groups and Sections
description](/guides/api/resources/organizations/groups).
requestBody:
required: true
content:
application/json:
schema:
description: Request body to create a section
type: object
required:
- name
properties:
name:
$ref: '#/components/schemas/SectionName'
org_id:
$ref: '#/components/schemas/SectionCreateOrgId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SectionCreateSuccessResponse'
'400':
description: Section name already exists
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/SectionCreateNameConflictResponse'
- $ref: >-
#/components/schemas/SectionCreateForbiddenCharactersResponse
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
get:
tags:
- Groups and Sections
operationId: getGroupSections
summary: Get Sections
description: >
Get all the sections for an organization.
For more information about the group system, see [the Groups and
Sections description](/guides/api/resources/organizations/groups).
parameters:
- $ref: '#/components/parameters/query_page'
- $ref: '#/components/parameters/query_filter_by_org_id'
- in: query
name: group_name_query
schema:
type: string
required: false
description: >-
Filter sections to only those containing at least one group whose
name contains this value (case-insensitive substring match).
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SectionsGetSuccessResponse'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/sections/{section_id}:
delete:
tags:
- Groups and Sections
operationId: deleteGroupSection
summary: Delete Section
description: >
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
group system, see [the Groups and Sections
description](/guides/api/resources/organizations/groups).
parameters:
- $ref: '#/components/parameters/path_section_id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SectionDeleteSuccessResponse'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
post:
tags:
- Groups and Sections
operationId: updateGroupSection
summary: Update Section
description: >
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
group system, see [the Groups and Sections
description](/guides/api/resources/organizations/groups).
parameters:
- $ref: '#/components/parameters/path_section_id'
requestBody:
required: true
content:
application/json:
schema:
description: Request body to update a section
type: object
required:
- name
properties:
name:
$ref: '#/components/schemas/SectionName'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SectionUpdateSuccessResponse'
'400':
description: Section name already exists
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/SectionCreateNameConflictResponse'
- $ref: >-
#/components/schemas/SectionCreateForbiddenCharactersResponse
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
get:
tags:
- Groups and Sections
operationId: getGroupSectionById
summary: Get Section by ID
description: >
Get a single section.
For more information about the group system, see [the Groups and
Sections description](/guides/api/resources/organizations/groups).
parameters:
- $ref: '#/components/parameters/path_section_id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SectionItem'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/sections/{section_id}/groups:
post:
tags:
- Groups and Sections
operationId: createGroup
summary: Create Group and set businesses
description: >
Create a new group.
This endpoint allows `Group Managers` to create new groups within the
system. For more information about the group system, see [the Groups
and Sections description](/guides/api/resources/organizations/groups).
⚠️ You must specify which businesses are part of the group using the
`business__in` parameter.
- If you don't specify any businesses, the group will be created with
**all** businesses. - To create an empty group, provide an empty array
in the `business__in` parameter.
parameters:
- $ref: '#/components/parameters/path_section_id'
requestBody:
required: true
content:
application/json:
schema:
description: Request body to create a group
type: object
required:
- name
- business__in
properties:
name:
$ref: '#/components/schemas/GroupV2Name'
business__in:
$ref: '#/components/schemas/business_ids'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GroupCreateSuccessResponse'
'400':
description: Group name already exists
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/SectionCreateNameConflictResponse'
- $ref: >-
#/components/schemas/SectionCreateForbiddenCharactersResponse
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/sections/{section_id}/groups/{group_id}:
post:
tags:
- Groups and Sections
operationId: updateGroup
summary: Update Group and set businesses
description: >
Update a group.
This endpoint allows you to modify the details of an existing group
within the system. Only `Group Managers` and higher roles can use this
endpoint. `Business Managers` are restricted from accessing it. For
more information about the group system, see [the Groups and Sections
description](/guides/api/resources/organizations/groups).
⚠️ You must specify which businesses are part of the group using the
`business__in` parameter.
- If you don't specify any businesses, the group will be updated to
include **all** businesses. - To update a group to be empty, provide an
empty array in the `business__in` parameter.
parameters:
- $ref: '#/components/parameters/path_section_id'
- $ref: '#/components/parameters/path_group_id'
requestBody:
required: true
content:
application/json:
schema:
description: Request body to update a group
type: object
required:
- name
- business__in
properties:
name:
$ref: '#/components/schemas/GroupV2Name'
business__in:
$ref: '#/components/schemas/business_ids'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GroupCreateSuccessResponse'
'400':
description: Group name already exists
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/SectionCreateNameConflictResponse'
- $ref: >-
#/components/schemas/SectionCreateForbiddenCharactersResponse
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
get:
tags:
- Groups and Sections
operationId: getGroup
summary: Get Group
description: >
Get a group and it's associated business IDs.
For more information about the group system, see [the Groups and
Sections description](/guides/api/resources/organizations/groups).
parameters:
- $ref: '#/components/parameters/path_section_id'
- $ref: '#/components/parameters/path_group_id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetGroupItem'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
delete:
tags:
- Groups and Sections
operationId: deleteGroup
summary: Delete Group
description: >
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
group system, see [the Groups and Sections
description](/guides/api/resources/organizations/groups).
parameters:
- $ref: '#/components/parameters/path_section_id'
- $ref: '#/components/parameters/path_group_id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GroupDeleteSuccessResponse'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/holidays/{country}:
get:
tags:
- Holidays
operationId: getHolidays
summary: Get holidays
description: >
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.
parameters:
- name: country
in: path
required: true
schema:
type: string
example: FR
description: >-
Country code from ISO 3166 international standard -
https://www.iban.com/country-codes
- name: lang
in: query
schema:
description: >-
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.
type: string
enum:
- fr
- en
- es
- it
- pt-br
- de
- ar
example: fr
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
holidays:
type: array
items:
type: object
properties:
name:
type: string
description: Name of bank holiday
date:
type: string
format: date
description: Date of bank holiday
example:
holidays:
- name: Armistice
date: '2023-11-11'
- name: Noël
date: '2023-12-25'
- name: Jour de l'an
date: '2024-01-01'
- name: Lundi de Pâques
date: '2024-04-01'
- name: Fête du Travail
date: '2024-05-01'
- name: Fête de la Victoire
date: '2024-05-08'
- name: Ascension
date: '2024-05-09'
- name: Lundi de Pentecôte
date: '2024-05-20'
- name: Fête nationale
date: '2024-07-14'
- name: Assomption
date: '2024-08-15'
- name: Toussaint
date: '2024-11-01'
- name: Christmas
date: '2024-12-25'
- name: New Year's Day
date: '2025-01-01'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
/org/search:
get:
tags:
- Organizations
summary: Search for organizations
operationId: searchOrganizations
description: >
This endpoint lets you search for organizations using filters. The
response is paginated (30 results per page).
parameters:
- $ref: '#/components/parameters/query_filter_by_org_id'
- in: query
name: query
schema:
type: string
required: false
description: Parameter to fuzzy search organizations on name or id
- name: alias
in: query
schema:
type: string
required: false
description: Parameter to search an organization by its alias
- $ref: '#/components/parameters/query_page'
- $ref: '#/components/parameters/query_per_page_1_100'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
description: Result object return by the API
properties:
page:
$ref: '#/components/schemas/current_page'
max_page:
$ref: '#/components/schemas/max_page'
count:
$ref: '#/components/schemas/count'
orgs:
type: array
description: The organizations complying with filter (30 max per page)
items:
$ref: '#/components/schemas/Org'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/org:
post:
tags:
- Organizations
summary: Create organization
operationId: createOrganization
description: >
This endpoint lets you create an organization. You have `WRITE` access
on your provider (ie. only possible if you have `PROVIDER` role).
requestBody:
required: true
content:
application/json:
schema:
type: object
description: JSON to create an organization
required:
- name
properties:
name:
$ref: '#/components/schemas/OrgName'
alias:
$ref: '#/components/schemas/OrgAlias'
max_businesses:
$ref: '#/components/schemas/OrgMaxBusinesses'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
description: Result object
properties:
status:
$ref: '#/components/schemas/RequestStatus'
org_id:
$ref: '#/components/schemas/OrgId'
alias:
$ref: '#/components/schemas/OrgAlias'
max_businesses:
$ref: '#/components/schemas/OrgMaxBusinesses'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/org/{org_id}:
get:
tags:
- Organizations
summary: Organization information
operationId: getOrganization
description: >
This endpoint lets you retrieve all the detail about a specific
organization. You need to have `READ` access to this organization.
parameters:
- $ref: '#/components/parameters/path_org_id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Org'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
post:
tags:
- Organizations
summary: Update organization
operationId: updateOrganization
description: >
This endpoint lets you update the information of an organization. You
need to have `WRITE` access on the organization.
parameters:
- $ref: '#/components/parameters/path_org_id'
requestBody:
required: true
content:
application/json:
schema:
type: object
description: The object to send to update an organization
properties:
name:
$ref: '#/components/schemas/OrgName'
alias:
$ref: '#/components/schemas/OrgAlias'
max_businesses:
$ref: '#/components/schemas/OrgMaxBusinesses'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
description: Result object
properties:
org_id:
$ref: '#/components/schemas/OrgId'
status:
$ref: '#/components/schemas/RequestStatus'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
delete:
tags:
- Organizations
summary: Delete organization
operationId: deleteOrganization
description: >
This endpoint lets you delete an organization. You need to have `WRITE`
access on your provider. When an organization gets deleted all the
resources linked to it are deleted (users and businesses). If the
organization still has businesses or users, it would raise an error if
you do not indicate `force="True"` in the JSON body.
parameters:
- $ref: '#/components/parameters/path_org_id'
- $ref: '#/components/parameters/organization_force_delete'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
description: Response object
properties:
status:
$ref: '#/components/schemas/RequestStatus'
org_id:
$ref: '#/components/schemas/OrgId'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/posts:
get:
summary: Search for post
description: |
This endpoint lets you browse through all your posts.
operationId: searchPost
tags:
- Posts
parameters:
- $ref: '#/components/parameters/query_business__in'
- $ref: '#/components/parameters/query_post_start_datetime'
- $ref: '#/components/parameters/query_post_end_datetime'
- $ref: '#/components/parameters/query_post_summary'
- $ref: '#/components/parameters/query_post_state_in'
- $ref: '#/components/parameters/query_post_topic_type'
- $ref: '#/components/parameters/query_post_topic_type_in'
- $ref: '#/components/parameters/query_page'
- $ref: '#/components/parameters/query_per_page_1_100'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ListResult'
- type: object
properties:
posts:
type: array
description: List of Post
items:
$ref: '#/components/schemas/Post'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
post:
summary: Create a post
description: >
This endpoint lets you create a post or a draft post on Google /
Facebook / Instagram.
The creation of a post will not happen in real time and might take a few
minutes.
A draft post can only be created by Org Admins and is not immediately
published.
An expiration date must be specified when creating a draft post.
In order to be published, a draft needs to be updated by a BM/GM user
before the expiration date.
operationId: createPost
tags:
- Posts
requestBody:
required: true
content:
application/json:
schema:
description: Request body to create a Post
type: object
required:
- business_search
- data
- publishers
properties:
business_search:
$ref: '#/components/schemas/PostBusinessSearch'
publishers:
$ref: '#/components/schemas/PostPublishers'
data:
$ref: '#/components/schemas/PostData'
is_draft:
description: >-
If true, the post will be created as a draft. You must then
also specify an `expiration_time` in the body's data.
type: boolean
default: false
send_notifications:
description: >-
If true, a notification email will be sent to all BM/GM
users that have access to this draft post
type: boolean
default: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/requestResponsePost'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/posts/{post_id}:
put:
summary: Update a post
description: >
This endpoint lets you update a post.
When used by a BM or GM user, this endpoint also serves to validate and
publish a draft post.
The update will not happen in real time and might take a few minutes
⚠️ Due to Instagram API limitations, **this operation has no effect on
Instagram posts**.
operationId: updatePost
tags:
- Posts
parameters:
- $ref: '#/components/parameters/path_post_id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PostUpdateData'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Post'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
delete:
summary: Delete a post
description: >
This endpoint lets you delete a post.
The deletion will not happen in real time and might take a few minutes.
⚠️ Due to Instagram API limitations, **this operation has no effect on
Instagram posts.**
operationId: deletePost
tags:
- Posts
parameters:
- $ref: '#/components/parameters/path_post_id'
responses:
'200':
description: OK
content:
application/json:
schema:
description: Response object
type: object
properties:
status:
$ref: '#/components/schemas/RequestStatus'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/place_action_links:
get:
tags:
- Place Action Links
summary: Get Place Action Links
description: |
Retrieve a list of available place action links.
operationId: getAvailablePlaceActionLinks
parameters:
- $ref: '#/components/parameters/query_place_action_link_lang'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetPlaceActionLinksResponse'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/publisher_states:
get:
summary: PublisherStates
description: |
Method to retrieve businesses diffusions states on publishers.
Can be filtered by:
- Business IDs
- Publishers
- States
operationId: getPublisherStates
tags:
- Presence
parameters:
- $ref: '#/components/parameters/query_business__in'
- name: publishers
in: query
required: false
description: List of requested publisher names
schema:
type: array
items:
type: string
example: facebook,google_my_business
- name: states
in: query
required: false
description: List of the requested states
schema:
type: array
items:
$ref: '#/components/schemas/state'
example: success,to_configure,pending
- name: per_page
in: query
schema:
type: integer
default: 5
minimum: 1
maximum: 100
description: Number of items to return per page. Currently limited to 100.
- name: page
in: query
required: false
description: Page requested
schema:
type: integer
example: 3
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/getPublisherStatesResponse'
examples:
publishers=[facebook, apple_direct]&states=[success,to_configure,pending]&page=1&per_page=1:
value:
businesses:
56465qz56d4q65zd4:
business_formatted_address: >-
1 Rue du Général de Gaulle, 52330
Colombey-les-Deux-Églises
business_id: 56465qz56d4q65zd4
business_name: La Boisserie
publishers:
apple_direct:
error_type: null
state: success
url_on_publisher: null
facebook:
error_type: PUBLISHER_CONNEXION
state: to_configure
url_on_publisher: http://facebook/boisserie
count: 1
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/publisher_errors/{business_id}:
post:
summary: PublisherErrors (DEPRECATED)
deprecated: true
description: >
⚠️ **DEPRECATED** - Please use [`POST
/v2/diffusion_errors/{business_id}`](/api-reference/presence/get-diffusion-errors-for-a-business)
instead.
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.
operationId: postPublisherErrors
tags:
- Presence
parameters:
- $ref: '#/components/parameters/business_id'
requestBody:
required: true
content:
application/json:
schema:
description: Request object
type: object
properties:
name:
$ref: '#/components/schemas/BusinessName'
org_id:
$ref: '#/components/schemas/OrgId'
country:
$ref: '#/components/schemas/BusinessCountry'
zipcode:
$ref: '#/components/schemas/BusinessZipcode'
city:
$ref: '#/components/schemas/BusinessCity'
region:
$ref: '#/components/schemas/BusinessRegion'
categories:
$ref: '#/components/schemas/BusinessCategories'
code:
$ref: '#/components/schemas/BusinessCode'
status:
$ref: '#/components/schemas/BusinessStatus'
address_full:
$ref: '#/components/schemas/AddressFull'
address2:
$ref: '#/components/schemas/Address2'
manual_lat:
$ref: '#/components/schemas/BusinessLatitude'
manual_long:
$ref: '#/components/schemas/BusinessLongitude'
lat:
$ref: '#/components/schemas/BusinessLatitude'
long:
$ref: '#/components/schemas/BusinessLongitude'
website_url:
$ref: '#/components/schemas/BusinessWebsite'
facebook_url:
$ref: '#/components/schemas/BusinessFacebookPage'
twitter_url:
$ref: '#/components/schemas/BusinessTwitter'
description_short:
$ref: '#/components/schemas/BusinessShortDescription'
description_long:
$ref: '#/components/schemas/BusinessLongDescription'
open_hours:
$ref: '#/components/schemas/OpenHours'
specific_hours:
$ref: '#/components/schemas/SpecificHours'
contacts:
$ref: '#/components/schemas/BusinessContactsCreate'
photos:
$ref: '#/components/schemas/Photos'
national_identification_number:
$ref: '#/components/schemas/BusinessNationalIdentificationNumber'
examples:
empty request body:
description: >-
Providing an empty request body will return errors based on
the business information stored in the database.
value: {}
filled request body:
description: >-
Providing a populated request body will return errors related
to the specified fields and their values only.
value:
name: Corner Shop
country: US
zipcode: '90210'
city: Beverly Hills
region: CA
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/postPublisherErrorsResponse'
examples:
without errors:
value: {}
with errors:
value:
hours:
open_hours:
le118000: 118000_supports_only_three_time_window_per_day
facebook: facebook_supports_only_two_time_window_per_day
apple_business_connect: >-
open_hours_less_than_15_min_interval_apple_business_connect
description:
description_short:
facebook: facebook_new_pages_description_short_too_long
contact:
phone_number:
google_my_business: invalid_field
snapchat: invalid_field
le118000: invalid_field
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/diffusion_errors/{business_id}:
post:
summary: Get diffusion errors for a business
operationId: getDiffusionErrorsForBusiness
tags:
- Presence
description: >
Get diffusion errors for a given business.
This endpoint returns diffusion errors grouped by publisher. Diffusion
errors are classified into two types:
- **Pre-check errors**: errors detected *before* sending data to
partners, based on the current business data.
- **Post-check errors**: errors detected *after* sending data to
partners, based on partner responses.
### Behavior
- If no input parameters are provided:
- Returns the **existing** pre-check and post-check errors stored in the database.
- If input parameters are provided:
- Applies the provided fields as an in-memory update on the business (without persisting).
- Recalculates pre-check errors based on these changes.
- Post-check errors are **not** recalculated in this case.
### Example Use Case
Use this endpoint during a business edit form to validate which
publishers would be affected by a change, without saving it yet.
parameters:
- $ref: '#/components/parameters/business_id'
requestBody:
required: false
content:
application/json:
schema:
description: Partial business update for simulating changes
type: object
properties:
name:
$ref: '#/components/schemas/BusinessName'
org_id:
$ref: '#/components/schemas/OrgId'
country:
$ref: '#/components/schemas/BusinessCountry'
zipcode:
$ref: '#/components/schemas/BusinessZipcode'
city:
$ref: '#/components/schemas/BusinessCity'
region:
$ref: '#/components/schemas/BusinessRegion'
categories:
$ref: '#/components/schemas/BusinessCategories'
code:
$ref: '#/components/schemas/BusinessCode'
status:
$ref: '#/components/schemas/BusinessStatus'
address_full:
$ref: '#/components/schemas/AddressFull'
address2:
$ref: '#/components/schemas/Address2'
manual_lat:
$ref: '#/components/schemas/BusinessLatitude'
manual_long:
$ref: '#/components/schemas/BusinessLongitude'
lat:
$ref: '#/components/schemas/BusinessLatitude'
long:
$ref: '#/components/schemas/BusinessLongitude'
website_url:
$ref: '#/components/schemas/BusinessWebsite'
facebook_url:
$ref: '#/components/schemas/BusinessFacebookPage'
twitter_url:
$ref: '#/components/schemas/BusinessTwitter'
description_short:
$ref: '#/components/schemas/BusinessShortDescription'
description_long:
$ref: '#/components/schemas/BusinessLongDescription'
open_hours:
$ref: '#/components/schemas/OpenHours'
specific_hours:
$ref: '#/components/schemas/SpecificHours'
contacts:
$ref: '#/components/schemas/BusinessContactsCreate'
photos:
$ref: '#/components/schemas/Photos'
national_identification_number:
$ref: '#/components/schemas/BusinessNationalIdentificationNumber'
examples:
empty request body:
description: Returns already stored pre-check and post-check errors
value: {}
filled request body:
description: Simulates changes and recalculates pre-check errors
value:
name: Corner Shop
country: US
zipcode: '90210'
city: Beverly Hills
region: CA
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
description: Diffusion errors grouped by section and field
properties:
address:
type: object
description: Errors in the address section
additionalProperties:
type: array
items:
type: object
properties:
publisher:
type: string
example: google
description: The publisher associated with the error
errors:
type: array
items:
type: string
example: ABC_NAME_ENTIRELY_NUMERIC
description: A list of error keys
context:
type: object
description: Optional context for the error
nullable: true
infos:
type: object
description: Errors in the infos section
additionalProperties:
type: array
items:
type: object
properties:
publisher:
type: string
errors:
type: array
items:
type: string
context:
type: object
nullable: true
advanced-settings:
type: object
description: Errors in the advanced settings section
additionalProperties:
type: array
items:
type: object
properties:
publisher:
type: string
errors:
type: array
items:
type: string
context:
type: object
nullable: true
examples:
no errors:
value: {}
with errors:
value:
infos:
name:
- publisher: google
errors:
- ABC_NAME_ENTIRELY_NUMERIC
- ABC_TOO_SHORT
context: null
advanced-settings:
national_identification_number:
- publisher: apple
errors:
- ABC_INVALID_ID
context:
id: '456'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/reviews:
get:
summary: Search for reviews
description: >
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).
By default, no state filter is applied: the response includes **all**
reviews,
including deleted ones. Use `state__in` / `state__notin` to narrow the
result.
operationId: searchReviews
tags:
- Reviews
parameters:
- $ref: '#/components/parameters/query_business__in'
- $ref: '#/components/parameters/query_business__notin'
- $ref: '#/components/parameters/query_content__isnull'
- $ref: '#/components/parameters/query_partner__in'
- $ref: '#/components/parameters/query_gmb_rating__in'
- $ref: '#/components/parameters/query_tripadvisor_rating__in'
- $ref: '#/components/parameters/query_recommended__in'
- $ref: '#/components/parameters/query_review_update_date__gte'
- $ref: '#/components/parameters/query_review_update_date__lte'
- $ref: '#/components/parameters/query_review_state'
- $ref: '#/components/parameters/query_review_state__notin'
- $ref: '#/components/parameters/query_tag_label_in'
- $ref: '#/components/parameters/query_review_without_tag'
- $ref: '#/components/parameters/query_keywords'
- $ref: '#/components/parameters/query_with_media_links'
- $ref: '#/components/parameters/query_page'
- $ref: '#/components/parameters/query_per_page_1_100'
- $ref: '#/components/parameters/review_query_order_by'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ListResult'
- type: object
properties:
reviews:
description: Filtered reviews
type: array
items:
$ref: '#/components/schemas/Review'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/reviews/{review_id}:
put:
summary: Update a review
description: |
Update the state of a review to treated/not_treated
operationId: updateReview
tags:
- Reviews
parameters:
- in: path
name: review_id
required: true
schema:
$ref: '#/components/schemas/ReviewId'
requestBody:
required: true
content:
application/json:
schema:
description: Request body to post a reply
type: object
required:
- review_id
- state
properties:
state:
description: Reply state
type: string
enum:
- treated
- not_treated
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Review'
- properties:
state:
example: treated
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/comments:
post:
tags:
- Reviews
summary: Post a reply to a review
description: This endpoint lets you reply to a given review.
operationId: ReplyToReview
requestBody:
required: true
content:
application/json:
schema:
description: Request body to post a reply
type: object
required:
- review_id
- content
properties:
review_id:
description: ID of the review you want to reply
type: number
example: 34
parent_id:
description: >
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.
type: number
example: 1234
content:
description: Content of your reply
type: string
format: text
example: Merci ❤️
reply_template_id:
description: ID of the reply template to use
type: number
example: 5678
reply_suggestion:
description: >-
Suggestion details for the reply, check how to retrieve
values in the [Fetch AI reply suggestion for
reviews](/api-reference/reviews/fetch-ai-reply-suggestion-for-reviews)
section.
type: object
properties:
reply_suggestion_id:
description: ID of the reply suggestion
type: number
example: 91011
reply_suggestion_modified:
description: Indicates if the suggestion was modified
type: boolean
example: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/comments/{comment_id}:
put:
tags:
- Reviews
summary: Modify a reply to a review
description: This endpoint lets you modify a given reply to a review.
operationId: ModifyReplyOfReview
parameters:
- in: path
name: comment_id
required: true
schema:
$ref: '#/components/schemas/CommentId'
requestBody:
required: true
content:
application/json:
schema:
description: Request body to modify a reply
type: object
required:
- content
properties:
content:
description: Content of your Reply
type: string
format: text
example: Merci ❤️
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
delete:
tags:
- Reviews
summary: Delete the given reply to a review
operationId: deleteReply
description: |
This endpoint lets you delete the reply to a review
parameters:
- in: path
name: comment_id
required: true
schema:
$ref: '#/components/schemas/CommentId'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- success
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/reviews/templates/search:
get:
summary: Search for review reply templates
description: |
This endpoint lets you browse through all your reply review templates.
operationId: searchTemplate
tags:
- Reviews
parameters:
- $ref: '#/components/parameters/query_page'
- $ref: '#/components/parameters/query_positive_template'
- $ref: '#/components/parameters/query_neutral_template'
- $ref: '#/components/parameters/query_negative_template'
- $ref: '#/components/parameters/query_language__in'
- $ref: '#/components/parameters/query_title_query'
- $ref: '#/components/parameters/query_text_query'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ListResult'
- type: object
properties:
reply_templates:
type: array
description: List of reply review templates
items:
$ref: '#/components/schemas/Template'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/reviews/templates/placeholders:
get:
summary: All available placeholders
description: >
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.
operationId: getTemplatePlaceholders
tags:
- Reviews
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TemplatePlaceholder'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/reviews/template:
post:
summary: Create a review reply template
description: |
This endpoint lets you create a review reply template.
operationId: createTemplate
tags:
- Reviews
requestBody:
required: true
content:
application/json:
schema:
description: Request body to post/edit a reply
type: object
required:
- language
- negative
- neutral
- positive
- text
- title
properties:
language:
$ref: '#/components/schemas/Lang'
negative:
$ref: '#/components/schemas/TemplateNegative'
neutral:
$ref: '#/components/schemas/TemplateNeutral'
positive:
$ref: '#/components/schemas/TemplatePositive'
text:
$ref: '#/components/schemas/TemplateText'
title:
$ref: '#/components/schemas/TemplateTitle'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/reviews/template/{template_id}:
delete:
summary: Delete a review reply template
description: |
This endpoint lets you delete a review reply template given its id.
operationId: deleteTemplate
tags:
- Reviews
parameters:
- $ref: '#/components/parameters/path_template_id'
responses:
'200':
description: OK
content:
application/json:
schema:
description: Response object
type: object
properties:
status:
$ref: '#/components/schemas/RequestStatus'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/reviews/fetch-suggestion/{review_id}/{index}:
get:
summary: Fetch AI reply suggestion for reviews
description: >
The AI reply suggestion is a service that generates a response to a
review based on the review content.
⚠️ This feature provides reply SUGGESTIONS, NOT AUTOMATIC REPLIES.
It is NOT designed for fully automating conversations. Similar to the
app,
a human reviewer is expected to validate the suggestion before selecting
it
in order to use [reply to a
review](/api-reference/reviews/post-a-reply-to-a-review) endpoint ⚠️
**How does the AI reply suggestion work?**
- First, call the Fetch AI reply suggestion service.
- Then retrieve the values and store them on the caller's side. It is
possible to request up to 3 suggestions per reply,
and after that, it's no longer possible; the suggestions are retained
once they're made, and that they can be found at the `index` (0, 1, or
2) of the parameters
- Finally, use the suggestion ID and pass it to `reply_suggestion`
request body when calling the [reply to a
review](/api-reference/reviews/post-a-reply-to-a-review) service to link
the response to the suggestion.
operationId: fetchReviewReplySuggestion
tags:
- Reviews
parameters:
- in: path
name: review_id
required: true
schema:
type: integer
example: 34
description: ID of the review for which we want an AI suggestion
- in: path
name: index
required: true
schema:
type: integer
minimum: 0
maximum: 2
description: Index of the reply suggestion (0, 1, or 2)
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReplySuggestion'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/presence_analytics/metrics:
get:
summary: Profile metrics for your business
description: >
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.
operationId: getPresenceAnalyticsMetrics
tags:
- Presence analytics
deprecated: false
parameters:
- $ref: '#/components/parameters/query_metrics_presence'
- $ref: '#/components/parameters/query_dimensions_presence'
- $ref: '#/components/parameters/query_order_by_presence'
- $ref: '#/components/parameters/pa_metrics_query_business__in'
- $ref: '#/components/parameters/pa_metrics_query_business__notin'
- $ref: '#/components/parameters/pa_metrics_query_city'
- $ref: '#/components/parameters/pa_metrics_query_query'
- $ref: '#/components/parameters/pa_metrics_query_filter_date__gte'
- $ref: '#/components/parameters/pa_metrics_query_filter_date__lte'
- $ref: '#/components/parameters/pa_pagination_query_page'
- $ref: '#/components/parameters/pa_pagination_query_per_page'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PresenceAnalyticsMetricsResponse'
examples:
metrics=business_impressions_desktop_maps,business_impressions_desktop_search,business_impressions_mobile_maps,business_impressions_mobile_search,business_direction_requests,call_clicks,website_clicks:
value:
page: 1
count: 1
max_page: 1
metrics:
- business_impressions_desktop_maps: 123
business_impressions_desktop_search: 123
business_impressions_mobile_maps: 123
business_impressions_mobile_search: 123
business_direction_requests: 123
call_clicks: 123
website_clicks: 123
dimensions=business & metrics=call_clicks:
value:
page: 1
count: 3
max_page: 1
metrics:
- call_clicks: 103
business_id: 59b2645db12ff60643ef832c
- call_clicks: 165
business_id: 60b2645fb12ff60643ef8344
- call_clicks: 28
business_id: 70b2645eb12ff60643ef833c
dimensions=month & metrics=website_clicks & order_by=website_clicks:
value:
page: 1
count: 2
max_page: 1
metrics:
- website_clicks: 57
date: '2019-08-01'
bucket: month
- website_clicks: 79
date: '2019-09-01'
bucket: month
dimensions=day,business & metrics=call_clicks & order_by=-day:
value:
page: 1
count: 6
max_page: 1
metrics:
- call_clicks: 48
business_id: 59b2645db12ff60643ef832c
date: '2019-09-30'
bucket: day
- call_clicks: 6
business_id: 59b2645fb12ff60643ef8344
date: '2019-09-30'
bucket: day
- call_clicks: 11
business_id: 59b2645db12ff60643ef832c
date: '2019-09-29'
bucket: day
- call_clicks: 0
business_id: 59b2645fb12ff60643ef8344
date: '2019-09-29'
bucket: day
- call_clicks: 2
business_id: 59b2645db12ff60643ef832c
date: '2019-09-28'
bucket: day
- call_clicks: 66
business_id: 59b2645fb12ff60643ef8344
date: '2019-09-28'
bucket: day
dimensions=week & metrics=website_clicks & filter_date__gte=2019-09-15 & filter_date__lte=2019-09-16:
value:
page: 1
count: 2
max_page: 1
metrics:
- website_clicks: 32
date: '2019-09-09'
bucket: week
- website_clicks: 164
date: '2019-09-16'
bucket: week
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/presence_analytics/keywords:
get:
summary: Profile keywords for your business
description: >
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)
- by branded status (branded vs discovery keywords)
The response can be aggregated by:
- business id
- by date: month or year
- by keyword
- by branded status (branded vs discovery)
The response can be ordered by:
- business id
- by date: month, or year
- by keyword
- by branded status
The response can be ordered in ascending or descending order by any of
the selected dimensions or metrics.
operationId: getPresenceAnalyticsKeywords
tags:
- Presence analytics
deprecated: false
parameters:
- $ref: '#/components/parameters/query_metrics_keywords'
- $ref: '#/components/parameters/query_dimensions_keywords'
- $ref: '#/components/parameters/query_order_by_keywords'
- $ref: '#/components/parameters/pa_keywords_query_business__in'
- $ref: '#/components/parameters/pa_keywords_query_filter_date__gte'
- $ref: '#/components/parameters/pa_keywords_query_filter_date__lte'
- $ref: '#/components/parameters/query_branded'
- $ref: '#/components/parameters/pa_pagination_query_page'
- $ref: '#/components/parameters/pa_pagination_query_per_page'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PresenceAnalyticsKeywordsResponse'
examples:
dimensions=month,keyword,branded:
value:
page: 1
count: 6
max_page: 1
keywords:
- branded: discovery
bucket: month
date: '2022-03-01'
keyword: bar
threshold: 42
- branded: branded
bucket: month
count: 9001
date: '2022-03-01'
keyword: foo
- branded: discovery
bucket: month
date: '2022-02-01'
keyword: bar
threshold: 42
- branded: branded
bucket: month
count: 9001
date: '2022-02-01'
keyword: foo
- branded: discovery
bucket: month
date: '2022-01-01'
keyword: bar
threshold: 42
- branded: branded
bucket: month
count: 9001
date: '2022-01-01'
keyword: foo
dimensions=month,keyword,branded&branded=true:
value:
page: 1
count: 3
max_page: 1
keywords:
- branded: branded
bucket: month
count: 9001
date: '2022-03-01'
keyword: foo
- branded: branded
bucket: month
count: 9001
date: '2022-02-01'
keyword: foo
- branded: branded
bucket: month
count: 9001
date: '2022-01-01'
keyword: foo
dimensions=month,keyword,branded&branded=false:
value:
page: 1
count: 3
max_page: 1
keywords:
- branded: discovery
bucket: month
date: '2022-03-01'
keyword: bar
threshold: 42
- branded: discovery
bucket: month
date: '2022-02-01'
keyword: bar
threshold: 42
- branded: discovery
bucket: month
date: '2022-01-01'
keyword: bar
threshold: 42
dimensions=keyword&branded=true:
value:
page: 1
count: 1
max_page: 1
keywords:
- count: 27003
keyword: foo
dimensions=branded:
value:
page: 1
count: 2
max_page: 1
keywords:
- branded: branded
threshold: 126
- branded: discovery
count: 27003
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/review_analytics/metrics:
get:
tags:
- Review analytics
summary: Get Review metrics
operationId: getReviewAnalyticsMetrics
description: >
**⚠️ This feature is available only for businesses subscribed to Review
Management. ⚠️**
All the operations to perform Reviews analytics.
This endpoint lets you view the statistics related to reviews made to
your businesses subscribed to
**Review Management**.
A request is composed of:
- One or more `metrics` which is the data you want to return
- An optional `dimensions` which defines how the data is grouped by
- If it is omitted, the request will return the metrics over all the data, based on your filters
- An optional `order_by` to define how the data is sorted
- Filters, the data can be filtered by:
- Businesses
- Groups
- Tags
- Review update date
Here is the list of all **metrics** available:
- `average_rating`: Average rating
- `rating_distribution`: Breakdown of the ratings (Number of 1-star
reviews, 2-star reviews, 3-star reviews, etc...)
- `reviews_count`: Number of reviews received
- `reply_time`: Breakdown of the reviews based on how fast (less or more
than 48 hours) they have been replied to (or not replied)
- `reply_means`: Breakdown of the review replies based on the reply
method used (manual reply, reply template, auto reply or AI suggestion)
- `average_rating_distribution`: Breakdown of your businesses based on
their average rating
- `rank`: Allows you to rank the users, businesses or groups based on
their performance on a metric (an order_by is required)
Here is the list of all **dimensions** available, and for each of them,
the list of metrics and sort order available:
- No dimension
- This allows you to get global stats across all your businesses
- Available metrics: `average_rating`, `rating_distribution`, `reviews_count`, `reply_time`, `reply_means`, `average_rating_distribution`
- Date dimensions: `day`, `week`, `month`, `year`
- This allows you to get the evolution of your metrics over time
- Available metrics: `average_rating`, `rating_distribution`, `reviews_count`, `reply_time`, `reply_means`
- Business and business group dimensions: `business`, `group`
- This allows you to see the metrics business by business or group by group (Requires group filter)
- Available metrics: `average_rating`, `rating_distribution`, `reviews_count`, `reply_time`, `reply_means`, `rank`
- `user`
- This allows you to see the metrics user by user
- Available metrics: `reply_time`, `reply_means`, `rank`
- `tag`
- This allows you to see the metrics tag by tag
- Available metrics: `average_rating`, `rating_distribution`, `reviews_count`
Here is the list of all **order_by** available (Add a minus `-` sign
before to order by decreasing order):
- `average_rating`: Sort by average rating
- `reviews_count`: Sort by review_count
- `reply_time__total`: Sort by number of reviews received
- `reply_means__total`: Sort by number of reviews that have been replied
- `ratio__rating_distribution__5`: Sort by the ratio of 5 star reviews
- `ratio__rating_distribution__negative`: Sort by the ratio of negative
reviews
- `ratio__reply_time__fast`: Sort by the ratio of reviews replied in
less than 2 days
- `ratio__reply_time__slow`: Sort by the ratio of reviews replied in
more than 2 days
- `ratio__reply_time__not_replied`: Sort by the ratio of reviews not
replied
- `ratio__reply_means__manual`: Sort by the ratio reviews replied
manually
- `ratio__reply_means__ai_suggestion`: Sort by the ratio reviews replied
using AI suggestion
- `ratio__reply_means__reply_template`: Sort by the ratio reviews
replied using reply template
- `ratio__reply_means__auto_reply`: Sort by the ratio reviews replied
using auto reply
To use an **order_by** parameter, its corresponding metric must be
included in the request.
(i.e.
to order by `average_rating`, you must include the `average_rating`
metric in the `metrics` parameter,
to order by `ratio__rating_distribution__5`, you must include the
`rating_distribution` metric in the `metrics` parameter,
and so on...)
parameters:
- $ref: '#/components/parameters/query_metrics_reviews'
- $ref: '#/components/parameters/query_dimensions_reviews'
- $ref: '#/components/parameters/query_order_by_reviews'
- $ref: '#/components/parameters/ra_query_business__in'
- $ref: '#/components/parameters/ra_query_business__notin'
- $ref: '#/components/parameters/ra_query_groups'
- $ref: '#/components/parameters/query_tags'
- $ref: '#/components/parameters/query_update_date__gte'
- $ref: '#/components/parameters/query_update_date__lte'
- $ref: '#/components/parameters/ra_query_page'
- $ref: '#/components/parameters/ra_query_per_page'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ListResult'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ReviewMetricsResponse'
examples:
'?metrics=average_rating&dimensions=business':
value:
page: 1
count: 2
max_page: 1
data:
- dimension: 59b2645db12ff60643ef832c
dimension_name: Business 1
dimension_info:
address_full: 190 rue Championnet
city: Paris
zipcode: '75018'
code: PTOCODE1
metrics:
average_rating: 2.31
- dimension: 60b2645fb12ff60643ef8344
dimension_name: Business 2
dimension_info:
address_full: 190 rue Championnet
city: Paris
zipcode: '75018'
code: PTOCODE2
metrics:
average_rating: 4.31
'?metrics=average_rating_distribution':
value:
page: 1
count: 1
max_page: 1
data:
- dimension: null
metrics:
average_rating_distribution:
4.3-5: 274
3.8-4.3: 124
3-3.8: 62
0-3: 5
'NULL': 4
'?metrics=average_rating,reviews_count&dimensions=day&filter_date__lte=2024-02-13&filter_date__gte=2024-02-11':
value:
page: 1
count: 3
max_page: 1
data:
- dimension: '2024-02-11'
metrics:
average_rating: 3.31
reviews_count: 123
- dimension: '2024-02-12'
metrics:
average_rating: 3.34
reviews_count: 123
- dimension: '2024-02-13'
metrics:
average_rating: 3.77
reviews_count: 123
'?metrics=reply_time,reply_means&dimensions=user':
value:
page: 1
count: 1
max_page: 1
data:
- dimension: 64477ae0264810a01c0a4edf
dimension_name: User 1
metrics:
reply_time:
fast: 11
slow: 32
not_replied: 0
total: 43
reply_means:
ai_suggestion: 20
manual: 3
auto_reply: 0
reply_template: 20
total: 43
'?metrics=rank,rating_distribution&dimensions=group&order_by=-ratio__rating_distribution__5&groups=1244,1245,1246':
value:
page: 1
count: 3
max_page: 1
data:
- dimension: 1244
dimension_name: Group 1244
metrics:
rank: 1
rating_distribution:
'1': 0
'2': 0
'3': 0
'4': 0
'5': 65
- dimension: 1245
dimension_name: Group 1245
metrics:
rank: 1
rating_distribution:
'1': 0
'2': 0
'3': 11
'4': 32
'5': 65
- dimension: 60b2645fb12ff60643ef8344
dimension_name: Group 1246
metrics:
rank: 3
rating_distribution:
'1': 19
'2': 0
'3': 0
'4': 0
'5': 0
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/reviews/stats:
get:
tags:
- Review analytics
summary: Global reviews statistics
operationId: getReviewAnalytics
deprecated: true
description: >
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.
parameters:
- $ref: '#/components/parameters/query_review_business__in'
- $ref: '#/components/parameters/query_keywords'
- $ref: '#/components/parameters/query_review_update_date__gte'
- $ref: '#/components/parameters/query_review_update_date__lte'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReviewsStatisticsResponse'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/reviews/qualitative-evolution:
get:
tags:
- Review analytics
summary: Qualitative evolution
operationId: getQualitativeEvolution
deprecated: true
description: >
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
parameters:
- $ref: '#/components/parameters/query_review_bucket'
- $ref: '#/components/parameters/query_review_cumulative'
- $ref: '#/components/parameters/query_review_business__in'
- $ref: '#/components/parameters/query_keywords'
- $ref: '#/components/parameters/query_review_update_date__gte'
- $ref: '#/components/parameters/query_review_update_date__lte'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
example:
- date: '2019-11-29'
average: 4.54
added: 50
cum_sum: 70
- date: '2019-12-05'
average: 4.34
added: 34
cum_sum: 104
- date: '2019-12-12'
average: 4.41
added: 4
cum_sum: 108
items:
type: object
properties:
date:
type: string
format: datetype
description: Start date of the bucket
average:
type: number
format: float
description: Average rating.
added:
type: integer
description: Number of reviews added during the current bucket.
cum_sum:
type: number
format: float
description: Cumulative sum of the number of reviews.
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/reviews/quantitative-evolution:
get:
tags:
- Review analytics
summary: Quantitative evolution
operationId: getQuantitativeEvolution
deprecated: true
description: >
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
parameters:
- $ref: '#/components/parameters/query_review_bucket'
- $ref: '#/components/parameters/query_review_business__in'
- $ref: '#/components/parameters/query_keywords'
- $ref: '#/components/parameters/query_review_update_date__gte'
- $ref: '#/components/parameters/query_review_update_date__lte'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
example:
- date: '2019-11-29'
added: 50
previous_sum: 20
cum_sum: 70
- date: '2019-12-05'
added: 34
previous_sum: 70
cum_sum: 104
- date: '2019-12-12'
added: 4
previous_sum: 104
cum_sum: 108
items:
type: object
properties:
date:
type: string
format: datetype
description: Start date of the bucket
added:
type: integer
description: Number of reviews added during the current bucket.
previous_sum:
type: number
description: >-
Cumulative sum of the number of reviews for the previous
bucket.
format: float
cum_sum:
type: number
format: float
description: Cumulative sum of the number of reviews.
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/review_booster/send_invitation:
post:
tags:
- Review Booster
summary: Send a review invitation
operationId: sendReviewInvitation
description: >
This endpoint lets you send an SMS to a customer to help them 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. Otherwise, the
template associated with the user will be used. If no template
exists, a new one will be generated.
Your business needs to be connected to a Google location and subscribed
to the Review Booster product. Therefore, this cannot be tested in the
Sandbox environment.
To prevent spamming, a new SMS can be sent to a specific phone number
only after 10 days since the last SMS was sent.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- business_id
- target_phone
properties:
business_id:
$ref: '#/components/schemas/BusinessId'
target_phone:
type: string
description: >-
Customer phone number, with the country calling code. Eg:
+33601020304
target_name:
type: string
description: Customer fullname
maxLength: 255
template_id:
type: integer
description: Id of the SMS template you want to use
deprecated: true
invite_content:
type: string
description: >-
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:
type: string
description: >-
To force invitation sending when a SMS has already been sent
to the customer
enum:
- 'True'
- 'False'
default: 'False'
examples:
Using template:
value:
business_id: 5409c35a97bbc544d8e26737
target_phone: '+33647385968'
target_name: John Doe
template_id: 31
Using invite content:
value:
business_id: 5409c35a97bbc544d8e26737
target_phone: '+33647385968'
target_name: John Doe
invite_content: >-
Hello, thank you for you visit ! Leave a review and tell us
more about your experience ! @link Thank you!
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
invitation_id:
$ref: '#/components/schemas/InvitationId'
status:
$ref: '#/components/schemas/RequestStatus'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/review_booster/search-invitation:
get:
tags:
- Review Booster
operationId: checkDuplicatedReviewInvitation
summary: Search for an invitation matching a set of criteria
description: >
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.
parameters:
- in: query
name: business_id
required: true
schema:
$ref: '#/components/schemas/BusinessId'
- in: query
name: target_phone
required: true
schema:
$ref: '#/components/schemas/TargetPhone'
- in: query
name: after
schema:
type: number
example: 1559148288
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ListResult'
- type: object
properties:
review_invitations:
type: array
description: List of invitations sent
items:
type: object
properties:
user_name:
type: string
example: Perceval
user_id:
type: string
example: 54b6733b9826bf1dd29af128
id:
type: string
example: 3d90efec-0d7f-4960-98c0-951d58dc14cb
sent_time:
type: string
example: '2019-06-06 11:57:27.274725+00:00'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
/review_booster/invitation_status:
get:
tags:
- Review Booster
summary: The status of a review invitation
operationId: getReviewInvitationStatus
description: "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.\n"
parameters:
- in: query
name: invitation_id
schema:
$ref: '#/components/schemas/InvitationId'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
invitation_id:
$ref: '#/components/schemas/InvitationId'
status:
type: string
description: the current state of the SMS
enum:
- CREATED
- SENT
- FAILED_SEND
- DELIVERED
- FAILED_DELIVERY
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
/review_booster/template:
get:
tags:
- Review Booster
summary: Template for a user
operationId: getInvitationTemplate
description: >
This endpoint lets you get your corresponding template. If no template
exists for the user, a template is created and sent back.
You need to be subscribed to the Review Booster product.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
template_id:
description: The id associated to the template
type: string
example: 3462
template:
description: The template content, with placeholder(s) not filled
type: string
example: Hello ${client_name}, please leave a review ${url}
status:
$ref: '#/components/schemas/RequestStatus'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
put:
tags:
- Review Booster
summary: Update the template of a user
operationId: setInvitationTemplate
description: >
This endpoint lets you update the template associated with the user.
3 placeholders are available for the template: `${client_name}`,
`${business_name}`, and `${url}`.
There are 2 main constraints: - `${url}` must be present in the
template sent. - The text should not contain more than 250 characters
(excluding placeholders).
The template must exist before the request is sent.
You need to be subscribed to the Review Booster product.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- template
properties:
template:
description: the template content, with placeholder(s) not filled
type: string
example: Hello ${client_name}, please leave a review ${url}
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/RequestStatus'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/review_booster/expeditor:
post:
tags:
- Review Booster
summary: Set the expeditor name of a business
operationId: setExpeditorName
description: >
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's length must be between 3 and 11 characters. No
special characters are allowed.
Your business must be subscribed to the Review Booster product.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- business_id
- expeditor_name
properties:
business_id:
$ref: '#/components/schemas/BusinessId'
expeditor_name:
description: The new expeditor name
type: string
example: Partoo
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
expeditor_name:
description: >-
the updated expeditor name, with no special characters and
between 3 and 11 characters
type: string
example: Partoo
status:
$ref: '#/components/schemas/RequestStatus'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
get:
tags:
- Review Booster
summary: The expeditor name of a business
operationId: getExpeditorName
description: >
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 the Review Booster product.
parameters:
- in: query
name: business_id
required: true
schema:
$ref: '#/components/schemas/BusinessId'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
expeditor_name:
description: The expeditor name used to send message
type: string
example: Partoo
status:
$ref: '#/components/schemas/RequestStatus'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/business/{business_id}/subscription:
get:
tags:
- Businesses
- Subscriptions
operationId: getBusinessSubscriptions
deprecated: true
summary: Subscriptions for your business
description: >
⚠️ This endpoint is deprecated. Please use the new endpoint
[`/business/{business_id}/plans`](/api-reference/subscriptions/update-businesss-plans)
instead. ⚠️
This endpoint lets you access the subscription of a business.
You need to have `READ` access on this business.
parameters:
- $ref: '#/components/parameters/business_id'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
description: Business subscriptions
properties:
presence_management:
$ref: '#/components/schemas/SubscriptionDetails'
review_management:
$ref: '#/components/schemas/SubscriptionDetails'
review_booster:
$ref: '#/components/schemas/SubscriptionDetails'
messages:
$ref: '#/components/schemas/SubscriptionDetails'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/business/{business_id}/subscribe:
post:
summary: Subscribe a business
operationId: subscribeBusiness
deprecated: true
description: >
⚠️ This endpoint is deprecated. Please use the new endpoint
[`/business/{business_id}/plans`](/api-reference/subscriptions/update-businesss-plans)
instead. ⚠️
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.
tags:
- Businesses
- Subscriptions
parameters:
- $ref: '#/components/parameters/business_id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
subscription_date:
type: number
description: >-
Timestamp representing the date on which the subscription
will start
example: 1540628702
products:
type: array
description: List of products
items:
$ref: '#/components/schemas/Product'
plan:
type: string
description: Any string that define your offer
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
presence_management:
oneOf:
- $ref: '#/components/schemas/ProductSubscribeResponseObject'
- $ref: '#/components/schemas/ProductUnsubscribeResponseObject'
review_management:
oneOf:
- $ref: '#/components/schemas/ProductSubscribeResponseObject'
- $ref: '#/components/schemas/ProductUnsubscribeResponseObject'
review_booster:
oneOf:
- $ref: '#/components/schemas/ProductSubscribeResponseObject'
- $ref: '#/components/schemas/ProductUnsubscribeResponseObject'
messages:
oneOf:
- $ref: '#/components/schemas/ProductSubscribeResponseObject'
- $ref: '#/components/schemas/ProductUnsubscribeResponseObject'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/business/{business_id}/unsubscribe:
post:
summary: Unsubscribe a business
operationId: unsubscribeBusiness
deprecated: true
description: >
⚠️ This endpoint is deprecated. Please use the new endpoint
[`/business/{business_id}/plans`](/api-reference/subscriptions/update-businesss-plans)
instead. ⚠️
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.
tags:
- Businesses
- Subscriptions
parameters:
- $ref: '#/components/parameters/business_id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
canceling_date:
type: number
description: >-
Timestamp representing the date on which the subscription
will stop to be valid
example: 1540628702
products:
type: array
description: List of products
items:
$ref: '#/components/schemas/Product'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
presence_management:
oneOf:
- $ref: '#/components/schemas/ProductSubscribeResponseObject'
- $ref: '#/components/schemas/ProductUnsubscribeResponseObject'
review_management:
oneOf:
- $ref: '#/components/schemas/ProductSubscribeResponseObject'
- $ref: '#/components/schemas/ProductUnsubscribeResponseObject'
review_booster:
oneOf:
- $ref: '#/components/schemas/ProductSubscribeResponseObject'
- $ref: '#/components/schemas/ProductUnsubscribeResponseObject'
messages:
oneOf:
- $ref: '#/components/schemas/ProductSubscribeResponseObject'
- $ref: '#/components/schemas/ProductUnsubscribeResponseObject'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/org/{org_id}/plans:
get:
tags:
- Subscriptions
- Organizations
summary: Get Organization's plans
operationId: organizationPlans
description: |
This endpoint lets you retrieve the organization's plans.
You need to be a Provider to access this endpoint.
parameters:
- $ref: '#/components/parameters/path_org_id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrgPlans'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
post:
tags:
- Subscriptions
- Organizations
summary: Update organization's plans
operationId: updateOrganizationPlans
description: >
This endpoint lets you update the plans of an organization.
You need to be a Provider to access this endpoint.
⚠️ You need to send **all the plans**, those not sent will be removed.
We advise you to call the GET endpoint first. ⚠️
parameters:
- $ref: '#/components/parameters/path_org_id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationPlansUpdate'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
description: Result object
properties:
org_id:
$ref: '#/components/schemas/OrgId'
status:
$ref: '#/components/schemas/RequestStatus'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/business/{business_id}/plans:
get:
tags:
- Subscriptions
- Businesses
summary: Get Business's plans
operationId: businessPlans
description: >
This endpoint lets you retrieve the business's plans. You need to
be a Provider to access this endpoint.
parameters:
- $ref: '#/components/parameters/business_id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessPlans'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
post:
tags:
- Subscriptions
- Businesses
summary: Update business's plans
operationId: updateBusinessPlans
description: >
This endpoint lets you update the plans of a business. You need to
be a Provider to access this endpoint. ⚠️You need to send all
the plans, those not sent will be removed. We advise you to call the
GET endpoint first. ⚠️
parameters:
- $ref: '#/components/parameters/business_id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessPlansUpdate'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
description: Result object
properties:
business_id:
$ref: '#/components/schemas/BusinessId'
status:
$ref: '#/components/schemas/RequestStatus'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/user/search:
get:
tags:
- Users
summary: Search for users
description: This endpoint lets you search for users using filters
operationId: searchUser
parameters:
- in: query
name: email
schema:
type: string
format: email
description: >-
Filter by user email. Value must be a valid email address.
Case-insensitive exact match.
required: false
- $ref: '#/components/parameters/query_filter_by_org_id'
- in: query
name: query
schema:
type: string
description: >-
Fuzzy search across the full name and email of users.
Case-insensitive.
- in: query
name: status
schema:
$ref: '#/components/schemas/UserStatus'
description: Filter users by status
- in: query
name: disabled
schema:
type: boolean
description: >-
If `true`, return only disabled users. If `false`, return only
active users.
- in: query
name: has_assigned_businesses
schema:
type: boolean
required: false
description: >
Filter users based on whether they have at least one assigned
business (`true`) or no assigned businesses (`false`).
- in: query
name: has_not_permission
schema:
type: string
required: false
description: >
Filter users who do *not* have the specified permission.
For available permissions and their names, use [GET
/api/v2/permissions](/api-reference/custom-roles/get-permissions) to
retrieve the full list of available permissions for your
organization.
- in: query
name: has_permission
schema:
type: string
required: false
description: >
Filter users who have the specified permission.
For available permissions and their names, use [GET
/api/v2/permissions](/api-reference/custom-roles/get-permissions) to
retrieve the full list of available permissions for your
organization.
- in: query
name: last_name
schema:
type: string
required: false
description: Filter users by last name (exact substring match, case-sensitive).
- in: query
name: role
schema:
$ref: '#/components/schemas/Role'
description: >
Filter users by role. Accepts a single value or a comma-separated
list.
required: false
- $ref: '#/components/parameters/query_display_business_ids'
- in: query
name: business_id
schema:
type: string
description: >
Filter by users having access to the business with the provided
id.
example: 5409c35a97bbc544d8e26737u
- $ref: '#/components/parameters/query_page'
- $ref: '#/components/parameters/query_per_page_1_100'
- in: query
name: order_by
schema:
type: string
enum:
- email
- first_name
- group_id
- id
- last_activity_date
- last_name
- org_id
- role
- status
- '-email'
- '-first_name'
- '-group_id'
- '-id'
- '-last_activity_date'
- '-last_name'
- '-org_id'
- '-role'
- '-status'
default: id
required: false
description: >
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:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ListResult'
- type: object
properties:
users:
type: array
description: List of users
items:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
/user/me:
get:
tags:
- Users
summary: My user
description: This endpoint lets you retrieve all the information about your user
operationId: getMyUser
parameters:
- $ref: '#/components/parameters/query_display_business_ids'
- name: org_id_custom_fields_permissions
in: query
description: >-
If you have access to more than one organization, you can specify
the org_id of the organization for which you want to retrieve the
`permissions` value.
required: false
schema:
type: integer
example: 42
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/UserWithFeatures'
- type: object
properties:
permissions:
description: >
The permissions the user has access to.
For more information about permissions, see the
[Custom Roles
guide](/guides/api/guides/custom-roles-and-permissions).
type: array
items:
type: string
example:
- access_help_center
- access_intercom
- account_facebook_manage
- account_google_manage
- bulk_modification
- business_edit
- business_edit_address
- business_edit_address2
- business_edit_attributes
- business_edit_attributes_url
- business_edit_categories
- business_edit_city
- business_edit_code
- business_edit_coordinates
- business_edit_country
- business_edit_description_long
- business_edit_description_short
- business_edit_email
- business_edit_facebook_url
- business_edit_fax
- business_edit_full_name
- business_edit_menus
- business_edit_more_hours
- business_edit_name
- business_edit_open_hours
- business_edit_phone_number
- business_edit_photo_cover
- business_edit_photo_logo
- business_edit_photo_secondary
- business_edit_services
- business_edit_siret
- business_edit_specific_hours
- business_edit_status
- business_edit_twitter_url
- business_edit_website_url
- business_edit_zipcode
- business_management_create_business
- business_management_import_business
- business_management_manage_groups
- custom_fields_edit
- custom_fields_edit__Decimal
- custom_fields_edit__Photos de voyage
- custom_fields_see_disabled_fields
- diffusion
- feedback_access_global_dashboard
- feedback_management
- feedback_result_reply
- jim_configuration
- jim_configuration_manage
- lead_collection_manage
- listing_status
- listing_status_manage
- messages
- messages_answer_conversation_custom
- messages_answer_conversation_facebook
- messages_answer_conversation_instagram
- messages_answer_conversation_sms
- messages_answer_conversation_whatsapp
- messages_conversation_assign
- messages_conversation_close
- messages_conversation_reopen
- messages_conversation_starters
- messages_conversation_starters_manage
- messages_lead_collection_read
- messages_templates_manage
- messages_templates_use
- messages_whatsapp_account
- messages_whatsapp_account_manage
- messages_widget
- messages_widget_manage
- partner_connection
- partner_connection_manage
- posts
- posts_manage
- posts_manage_bulk
- presence_analytics
- review_analytics
- review_analytics_download
- review_booster
- review_booster_edit_expeditor_name
- review_booster_manage_sms_template
- review_booster_share_link
- review_booster_show_qr_code
- review_download
- review_flag
- review_manage_auto_reply_with_comments
- review_manage_auto_reply_without_comments
- review_manage_state
- review_management
- review_reply_negative_reviews
- review_reply_neutral_reviews
- review_reply_positive_reviews
- review_reply_suggestion
- review_reply_template_manage
- review_reply_template_use
- review_tags_assign
- review_tags_manage
- user_management
- user_management_manage
'401':
$ref: '#/components/responses/401'
/user:
post:
tags:
- Users
summary: Create user
description: >
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 organization of the user you want
to create.
If you want to have an `invited` user but send the invitation email
later, you have to send the `send_invitation` parameter as `False` and a
`status` parameter to `invited`.
You will then have to call the [invitation
endpoint](/api-reference/users/invite-user) to send the invitation email
to the user.
operationId: createUser
requestBody:
required: true
content:
application/json:
schema:
description: Request body to create a user
type: object
required:
- email
- first_name
- last_name
properties:
email:
description: User email (must be unique will return otherwise)
type: string
format: email
first_name:
$ref: '#/components/schemas/UserFirstName'
last_name:
$ref: '#/components/schemas/UserLastName'
org_id:
$ref: '#/components/schemas/UserCreateUpdateOrgId'
accesses:
$ref: '#/components/schemas/accesses'
business_ids:
description: >
The list of business to which the user has access to. Will
be taken into account only if user has `BUSINESS_MANAGER`
role.
type: array
items:
type: string
role:
$ref: '#/components/schemas/RoleWithoutProvider'
custom_role:
$ref: '#/components/schemas/CustomRoleApiId'
sidebar_pages:
deprecated: true
allOf:
- $ref: '#/components/schemas/SidebarPages'
description: >
**DEPRECATED**: This parameter is deprecated in favor of the
new Custom Roles system. See the [Custom Roles & Permissions
guide](/guides/api/guides/custom-roles-and-permissions) for
migration information.
List of features the user can access from the sidebar.
If not provided in the payload or set to `null`, then the
user will be given all the available features of their
organization.
send_invitation:
description: >
Send an invitation email to the User.
If you want to have an `invited` user but send the
invitation email later, you have to send the
`send_invitation` parameter as `False` and a `status`
parameter to `invited`.
You will then have to call the [invitation
endpoint](/api-reference/users/invite-user) to send the
invitation email to the user.
type: boolean
default: false
status:
$ref: '#/components/schemas/UserStatus'
password:
$ref: '#/components/schemas/Password'
lang:
$ref: '#/components/schemas/Lang'
sso_only:
$ref: '#/components/schemas/SsoOnly'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
id:
$ref: '#/components/schemas/UserId'
status:
$ref: '#/components/schemas/RequestStatus'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/user/{user_id}:
get:
tags:
- Users
summary: User information
description: >
This endpoint lets you retrieve all the information on a user. You need
to have `READ` access to this users.
operationId: getUser
parameters:
- $ref: '#/components/parameters/path_user_id'
- $ref: '#/components/parameters/query_display_business_ids'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UserWithFeatures'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
post:
tags:
- Users
summary: Update user
description: >
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.
operationId: updateUser
parameters:
- $ref: '#/components/parameters/path_user_id'
requestBody:
required: true
content:
application/json:
schema:
description: Request body to update a user.
type: object
properties:
email:
$ref: '#/components/schemas/UserEmail'
first_name:
$ref: '#/components/schemas/UserFirstName'
last_name:
$ref: '#/components/schemas/UserLastName'
org_id:
$ref: '#/components/schemas/UserCreateUpdateOrgId'
accesses:
$ref: '#/components/schemas/accesses'
business_ids:
description: >
The list of business to which the user has access to. Will
be taken into account only if user has `BUSINESS_MANAGER`
role.
type: array
items:
type: string
role:
$ref: '#/components/schemas/RoleWithoutProvider'
custom_role:
$ref: '#/components/schemas/CustomRoleApiId'
sidebar_pages:
deprecated: true
allOf:
- $ref: '#/components/schemas/SidebarPages'
description: >
**DEPRECATED**: This parameter is deprecated in favor of the
new Custom Roles system. See the [Custom Roles & Permissions
guide](/guides/api/guides/custom-roles-and-permissions) for
migration information.
List of features the user can access from the sidebar.
status:
$ref: '#/components/schemas/UserStatus'
disabled:
type: boolean
description: The state of the User account.
password:
$ref: '#/components/schemas/Password'
lang:
$ref: '#/components/schemas/Lang'
sso_only:
$ref: '#/components/schemas/SsoOnly'
receive_reviews_email_notifications:
description: >-
The parameter decides if the user subscribes to negative
reviews email notifications
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
id:
$ref: '#/components/schemas/UserId'
status:
type: string
enum:
- success
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
delete:
summary: Delete user
description: >
This endpoint lets you delete a user. You need to have `WRITE` access to
this user.
operationId: deleteUser
tags:
- Users
parameters:
- $ref: '#/components/parameters/path_user_id'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
id:
$ref: '#/components/schemas/UserId'
status:
type: string
enum:
- success
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/user/{user_id}/preferences:
get:
tags:
- Users
summary: User preferences
description: >
This endpoint lets you retrieve all the information about a user's
preferences on notifications. You need to have `READ` access to this
user.
Here are the default values for newly created users
```json
{
"reports": {
"review_management_daily": true,
"review_management_weekly": true,
"review_management_monthly": true,
"daily_review_preferences": {
"partners": [
"google_my_business",
"facebook"
],
"review_type": 2
}
},
"receive_negative_reviews_email_notifications": false
}
```
operationId: getUserPreferences
parameters:
- $ref: '#/components/parameters/path_user_id'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
reports:
$ref: '#/components/schemas/UserReports'
receive_negative_reviews_email_notifications:
$ref: >-
#/components/schemas/ReceiveNegativeReviewsEmailNotifications
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
post:
summary: Set user preferences
description: >
This endpoint lets you update all the information about a user's
preferences on notifications. You need to have `WRITE` access to this
user.
operationId: updateUserPreferences
tags:
- Users
parameters:
- $ref: '#/components/parameters/path_user_id'
requestBody:
required: true
content:
application/json:
schema:
properties:
reports:
$ref: '#/components/schemas/UserReports'
receive_negative_reviews_email_notifications:
$ref: >-
#/components/schemas/ReceiveNegativeReviewsEmailNotifications
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
id:
$ref: '#/components/schemas/UserId'
status:
type: string
enum:
- success
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/user/{user_id}/invite:
post:
tags:
- Users
summary: Invite user
description: >
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.
operationId: reinviteUser
parameters:
- $ref: '#/components/parameters/path_user_id'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/RequestStatus'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/user/{user_id}/businesses:
get:
tags:
- Users
summary: User businesses
description: >
This endpoint lets you retrieve the list of businesses which the
selected user has `READ` access to.
operationId: getUserBusinesses
parameters:
- $ref: '#/components/parameters/path_user_id'
- $ref: '#/components/parameters/query_page'
- $ref: '#/components/parameters/query_per_page_1_100'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ListResult'
- type: object
properties:
businesses:
description: User businesses
type: array
items:
$ref: '#/components/schemas/Business'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/feedback/feedback_form:
get:
summary: Search for feedback forms
description: >
The Feedback Management API is currently in **BETA**, therefore the
following endpoints are subject to modification, given a **2 week
notice**.
If you are planning to use any of them, please **notify us** so we will
be able to keep you informed about upcoming changes.
This endpoint lets you search for the feedback forms of your
organization.
The response is paginated (30 results per page).
operationId: searchFeedbackForm
tags:
- Feedback Management
x-badges:
- name: Beta
position: after
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ListResult'
- type: object
properties:
items:
description: Filtered feedback forms
type: array
items:
$ref: '#/components/schemas/feedback_form'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/feedback/feedback_form/{feedback_form_id}:
put:
summary: Update a feedback form
description: >
The Feedback Management API is currently in **BETA**, therefore the
following endpoints are subject to modification, given a **2 week
notice**.
If you are planning to use any of them, please **notify us** so we will
be able to keep you informed about upcoming changes.
This endpoint lets you modify the properties of your feedback forms.
operationId: updateFeedbackForm
tags:
- Feedback Management
x-badges:
- name: Beta
position: after
parameters:
- in: path
name: feedback_form_id
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
description: Request body to post a reply
type: object
required:
- content
properties:
display_name:
allOf:
- $ref: '#/components/schemas/display_name'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/feedback_form'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/feedback/feedback_result:
get:
summary: Search for feedback results
description: >
The Feedback Management API is currently in **BETA**, therefore the
following endpoints are subject to modification, given a **2 week
notice**.
If you are planning to use any of them, please **notify us** so we will
be able to keep you informed about upcoming changes.
This endpoint lets you search for the feedback results of your
businesses.
The response is paginated (30 results per page).
operationId: searchFeedbackResults
tags:
- Feedback Management
x-badges:
- name: Beta
position: after
parameters:
- $ref: '#/components/parameters/query_business__in'
- $ref: '#/components/parameters/query_business__notin'
- $ref: '#/components/parameters/state__in'
- $ref: '#/components/parameters/created__lte'
- $ref: '#/components/parameters/created__gte'
- $ref: '#/components/parameters/nps__lte'
- $ref: '#/components/parameters/nps__gte'
- $ref: '#/components/parameters/nps__in'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/optin'
- $ref: '#/components/parameters/feedback_form_ids'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ListResult'
- type: object
properties:
items:
description: Filtered feedback results
type: array
items:
$ref: '#/components/schemas/feedback_result'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/feedback/feedback_result/{feedback_result_id}/reply:
post:
summary: Reply to a feedback result
description: >
The Feedback Management API is currently in **BETA**, therefore the
following endpoints are subject to modification, given a **2 week
notice**.
If you are planning to use any of them, please **notify us** so we will
be able to keep you informed about upcoming changes.
This endpoint lets you reply to a feedback result.
In order to be able to reply to a feedback result:
- The `optin` property of the corresponding feedback result must be true
- The `email_reply_source` of the corresponding feedback form must be
set
- The `email_reply_subject` of the corresponding feedback form must be
set
operationId: replyFeedbackResult
tags:
- Feedback Management
x-badges:
- name: Beta
position: after
parameters:
- in: path
name: feedback_result_id
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
description: Request body to post a reply
type: object
required:
- content
properties:
content:
description: Content of your reply
type: string
format: text
example: Merci ❤️
reply_suggestion:
description: Suggestion details for the reply
type: object
properties:
reply_suggestion_id:
type: integer
description: ID of the reply suggestion
example: 123
reply_suggestion_modified:
type: boolean
description: Indicates if the reply suggestion was modified
example: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/feedback_result_reply'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/feedback/feedback_result/fetch-suggestion/{feedback_result_id}/{index}:
get:
summary: Fetch AI reply suggestion for feedback results
description: >
The Feedback Management API is currently in **BETA**, therefore the
following endpoints are subject to modification, given a **2 week
notice**.
If you are planning to use any of them, please **notify us** so we will
be able to keep you informed about upcoming changes.
Fetch a reply suggestion generated by AI for a specific feedback result.
operationId: fetchFeedbackReplySuggestion
tags:
- Feedback Management
x-badges:
- name: Beta
position: after
parameters:
- in: path
name: feedback_result_id
required: true
schema:
type: integer
description: ID of the feedback result
- in: path
name: index
required: true
schema:
type: integer
minimum: 0
maximum: 2
description: Index of the reply suggestion (0, 1, or 2)
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/feedback_result_reply_suggestion'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/feedback/analytics/metrics:
get:
summary: Feedback analytics metrics
description: >
**⚠️ This feature is available only for organisations subscribed to
Feedback Management. ⚠️**
Retrieve aggregated feedback analytics data for your organisation.
A request is composed of:
- One or more **`metrics`** — the data you want to compute (required)
- An optional **`dimensions`** — how the data is grouped
- If omitted, the request returns the aggregated totals across all data matching the filters
- An optional **`order_by`** — how the rows are sorted
- **Filters** to narrow the data:
- By business (`business__in`, `business__notin`)
- By group or group section (`groups`, `group_section_id`)
- By date range (`filter_date__gte`, `filter_date__lte`)
- By survey or field (`survey__in`, `survey_field__in`, `survey_field_type__in`)
- By NPS score (`result_nps_score__in`)
- By free-text comment (`verbatim_query`)
- By data quality issues (`issues__in`, `issues__notin`)
- By business location (`city`, `query`)
**Metrics** are grouped into five categories:
| Category | Prefix | Examples |
|---|---|---|
| Survey | `survey.` | `survey.response_rate`, `survey.nb__sent` |
| CSAT | `result.csat.` | `result.csat.score`, `result.csat.avg_score` |
| NPS | `result.nps.` | `result.nps.score`, `result.nps.promoters` |
| Response | `response.` | `response.avg_response_time`,
`response.method.nb__ai` |
| Result field | `result_field.` | `result_field.rating`,
`result_field.choices` |
**Dimensions** control how rows are grouped:
- Entity: `business`, `user`, `feedback_form`, `group`, `group_section`,
`feedback_form_field`, `result`
- Time: `day`, `month`, `year`
**Excel download**: add `download=true` to receive the data as an
`.xlsx` file instead of JSON.
Use `table_name` to customise the filename.
**Metadata**: add `metadata=true` to include full entity objects
(businesses, forms, users…)
alongside the `data` array. Useful for resolving IDs to display names
without extra API calls.
operationId: getFeedbackAnalyticsMetrics
tags:
- Feedback analytics
deprecated: false
parameters:
- $ref: '#/components/parameters/query_metrics'
- $ref: '#/components/parameters/query_dimensions'
- $ref: '#/components/parameters/fm_analytics_query_order_by'
- $ref: '#/components/parameters/fm_analytics_query_business__in'
- $ref: '#/components/parameters/fm_analytics_query_business__notin'
- $ref: '#/components/parameters/query_user__in'
- $ref: '#/components/parameters/fm_analytics_query_groups'
- $ref: '#/components/parameters/query_group_section_id'
- $ref: '#/components/parameters/fm_analytics_query_city'
- $ref: '#/components/parameters/fm_analytics_query_query'
- $ref: '#/components/parameters/fm_analytics_query_filter_date__gte'
- $ref: '#/components/parameters/fm_analytics_query_filter_date__lte'
- $ref: '#/components/parameters/query_survey__in'
- $ref: '#/components/parameters/query_survey_field__in'
- $ref: '#/components/parameters/query_survey_field_type__in'
- $ref: '#/components/parameters/query_result_nps_score__in'
- $ref: '#/components/parameters/query_result_id__in'
- $ref: '#/components/parameters/query_verbatim_query'
- $ref: '#/components/parameters/query_issues__in'
- $ref: '#/components/parameters/query_issues__notin'
- $ref: '#/components/parameters/query_metadata'
- $ref: '#/components/parameters/query_download'
- $ref: '#/components/parameters/query_table_name'
- $ref: '#/components/parameters/fm_analytics_query_page'
- $ref: '#/components/parameters/fm_analytics_query_per_page'
responses:
'200':
description: >
OK.
When `download=true`, the response is an Excel file (`.xlsx`) with a
`Content-Disposition: attachment` header containing the generated
filename,
instead of the JSON body described below.
content:
application/json:
schema:
$ref: '#/components/schemas/FeedbackAnalyticsResponse'
examples:
'?metrics=result.csat.score,result.csat.avg_score':
value:
page: 1
count: 1
max_page: 1
data:
- result.csat.score: 87.5
result.csat.avg_score: 4.38
metadata:
feedback_form: null
feedback_form_field: null
result: null
business: null
group: null
group_section: null
user: null
'?metrics=result.csat.score&dimensions=business':
value:
page: 1
count: 2
max_page: 1
data:
- result.csat.score: 91.2
business_id: 59b2645db12ff60643ef832c
- result.csat.score: 83.4
business_id: 60b2645fb12ff60643ef8344
metadata:
feedback_form: null
feedback_form_field: null
result: null
business: null
group: null
group_section: null
user: null
'?metrics=result.nps.score,result.nps.promoters&dimensions=month&filter_date__gte=2024-01-01&filter_date__lte=2024-03-31':
value:
page: 1
count: 3
max_page: 1
data:
- result.nps.score: 42
result.nps.promoters: 58
date: '2024-01-01'
- result.nps.score: 45
result.nps.promoters: 63
date: '2024-02-01'
- result.nps.score: 50
result.nps.promoters: 71
date: '2024-03-01'
metadata:
feedback_form: null
feedback_form_field: null
result: null
business: null
group: null
group_section: null
user: null
'?metrics=survey.response_rate,survey.nb__sent&dimensions=feedback_form&metadata=true':
value:
page: 1
count: 2
max_page: 1
data:
- survey.response_rate: 0.72
survey.nb__sent: 250
feedback_form_id: 674d791c13c9d976e20001b1
- survey.response_rate: 0.61
survey.nb__sent: 180
feedback_form_id: 674d791c13c9d976e20001b2
metadata:
feedback_form:
- id: 674d791c13c9d976e20001b1
display_name: Post-visit Survey
- id: 674d791c13c9d976e20001b2
display_name: Annual NPS Survey
feedback_form_field: null
result: null
business: null
group: null
group_section: null
user: null
'?metrics=survey.sent,survey.delivered,survey.opened,survey.clicked,survey.error_bounces&dimensions=feedback_form':
value:
page: 1
count: 1
max_page: 1
data:
- survey.sent: 120
survey.delivered: 118
survey.opened: 89
survey.clicked: 42
survey.error_bounces: 2
feedback_form_id: 674d791c13c9d976e20001b1
'?metrics=result.csat.score&dimensions=business,month&order_by=-result.csat.score':
value:
page: 1
count: 4
max_page: 1
data:
- result.csat.score: 95
business_id: 59b2645db12ff60643ef832c
date: '2024-02-01'
- result.csat.score: 90
business_id: 60b2645fb12ff60643ef8344
date: '2024-02-01'
- result.csat.score: 88
business_id: 59b2645db12ff60643ef832c
date: '2024-01-01'
- result.csat.score: 75
business_id: 60b2645fb12ff60643ef8344
date: '2024-01-01'
metadata:
feedback_form: null
feedback_form_field: null
result: null
business: null
group: null
group_section: null
user: null
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/webhooks:
get:
tags:
- Webhooks
operationId: getWebhookList
summary: Get a list of webhook configurations
description: |
This endpoint returns the list of webhook configurations.
parameters:
- $ref: '#/components/parameters/org_id'
- $ref: '#/components/parameters/query_page'
- $ref: '#/components/parameters/query_per_page_1_100'
x-badges:
- name: Beta
position: after
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ListResult'
- type: object
properties:
items:
type: array
description: List of webhook configurations
items:
$ref: '#/components/schemas/WebhookItem'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
post:
tags:
- Webhooks
operationId: Webhook
summary: Create webhook configurations
description: |
This endpoint create webhook configurations.
x-badges:
- name: Beta
position: after
parameters:
- $ref: '#/components/parameters/org_id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWebhooksPayload'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- type: object
properties:
items:
type: array
description: List of created webhook configurations
items:
$ref: '#/components/schemas/WebhookItem'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/webhooks/{webhook_id}:
get:
tags:
- Webhooks
operationId: getWebhook
summary: Get a webhook configuration
description: |
This endpoint returns the details of a webhook configuration.
x-badges:
- name: Beta
position: after
parameters:
- $ref: '#/components/parameters/webhook_id'
- $ref: '#/components/parameters/org_id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookItem'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
patch:
tags:
- Webhooks
operationId: patchWebhook
summary: Update a webhook configuration
description: |
This endpoint updates a webhook configuration.
x-badges:
- name: Beta
position: after
parameters:
- $ref: '#/components/parameters/webhook_id'
- $ref: '#/components/parameters/org_id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWebhookPayload'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookItem'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
delete:
tags:
- Webhooks
operationId: deleteWebhook
summary: Delete a webhook configuration
description: |
This endpoint deletes a webhook configuration.
x-badges:
- name: Beta
position: after
parameters:
- $ref: '#/components/parameters/webhook_id'
- $ref: '#/components/parameters/org_id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookDeleteSuccess'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/webhooks/tryout:
post:
tags:
- Webhooks
operationId: postWebhookTryout
summary: Send test webhook payloads
description: >
This endpoint let you try webhook configurations by sending test
payloads. This currently supports only one webhook configuration per
request, entries after the first one will be ignored. Payloads are
created by the latest data of the specified event type, or if not
available a default payload will be sent. The request is similar
to a regular webhook, but also contains an additional
`X-Partoo-Webhook-Tryout` header.
x-badges:
- name: Beta
position: after
parameters:
- $ref: '#/components/parameters/org_id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWebhooksPayload'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- type: object
properties:
items:
type: array
description: Result of the tests.
items:
$ref: '#/components/schemas/WebhookTryoutResult'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/webhooks/events:
get:
tags:
- Webhooks
operationId: getWebhooksEvents
summary: List available webhook events
description: >
This endpoint returns the list of the webhook events available to the
organization, depending on the subscribed products.
x-badges:
- name: Beta
position: after
parameters:
- $ref: '#/components/parameters/org_id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEventTypes'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
webhooks:
businessCreated:
post:
operationId: business_created
tags:
- Webhooks Events
summary: New Business Created
description: |
This event is triggered when a Business is created in Partoo Database.
The event payload contains the event type and the business contents.
requestBody:
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- business_created
payload:
type: object
properties:
business:
$ref: '#/components/schemas/Business'
responses:
'200':
description: |
Return a 200 status to indicate that the event was properly received
'500':
description: >
An error in range 500-599 will trigger a retry from webhook delivery
system, up to 5 times, with an exponential backout.
> ⚠️ You may have to deal with events not received in order
security: []
businessUpdated:
post:
operationId: business_updated
tags:
- Webhooks Events
summary: Business Updated
description: >
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.
requestBody:
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- business_updated
payload:
type: object
properties:
business:
$ref: '#/components/schemas/Business'
responses:
'200':
description: |
Return a 200 status to indicate that the event was properly received
'500':
description: >
An error in range 500-599 will trigger a retry from webhook delivery
system, up to 5 times, with an exponential backout.
> ⚠️ You may have to deal with events not received in order
security: []
businessDeleted:
post:
operationId: business_deleted
tags:
- Webhooks Events
summary: Business Deleted
description: |
This event is triggered when a Business is removed from Partoo Database.
The event payload contains the event type and the business id.
requestBody:
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- business_deleted
payload:
type: object
properties:
business_id:
$ref: '#/components/schemas/BusinessId'
responses:
'200':
description: |
Return a 200 status to indicate that the event was properly received
'500':
description: >
An error in range 500-599 will trigger a retry from webhook delivery
system, up to 5 times, with an exponential backout.
> ⚠️ You may have to deal with events not received in order
security: []
messageCreated:
post:
operationId: message_created
tags:
- Webhooks Events
summary: Message Created
description: |
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.
requestBody:
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- message_created
payload:
$ref: '#/components/schemas/MessageCreatedEvent'
responses:
'200':
description: |
Return a 200 status to indicate that the event was properly received
'500':
description: >
An error in range 500-599 will trigger a retry from webhook delivery
system, up to 5 times, with an exponential backout.
> ⚠️ You may have to deal with events not received in order
security: []
messageUpdated:
post:
operationId: message_updated
tags:
- Webhooks Events
summary: Message Updated
description: >
This event is triggered if the field of a message is updated (example:
`status`, `is_deleted`).
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](/api-reference/messages/retry-send-message).
The event payload contains the event type, the content of the updated
message and additional information about the conversation.
requestBody:
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- message_updated
payload:
$ref: '#/components/schemas/MessageCreatedEvent'
responses:
'200':
description: |
Return a 200 status to indicate that the event was properly received
'500':
description: >
An error in range 500-599 will trigger a retry from webhook delivery
system, up to 5 times, with an exponential backout.
> ⚠️ You may have to deal with events not received in order
security: []
leadReceived:
post:
operationId: lead_received
tags:
- Webhooks Events
summary: Lead Received
description: |
This event is triggered when a Lead is added in Partoo Database.
The event payload contains the event type and the lead contents.
requestBody:
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- lead_received
payload:
type: object
$ref: '#/components/schemas/LeadWebhook'
responses:
'200':
description: |
Return a 200 status to indicate that the event was properly received
'500':
description: >
An error in range 500-599 will trigger a retry from webhook delivery
system, up to 5 times, with an exponential backout.
> ⚠️ You may have to deal with events not received in order
security: []
reviewCreated:
post:
operationId: review_created
tags:
- Webhooks Events
summary: Review Created
description: |
This event is triggered when a business receives a new review.
The event payload contains the event type and the review contents.
requestBody:
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- review_created
payload:
type: object
properties:
review:
$ref: '#/components/schemas/Review'
responses:
'200':
description: |
Return a 200 status to indicate that the event was properly received
'500':
description: >
An error in range 500-599 will trigger a retry from webhook delivery
system, up to 5 times, with an exponential backout.
> ⚠️ You may have to deal with events not received in order
security: []
reviewUpdated:
post:
operationId: review_updated
tags:
- Webhooks Events
summary: Review Updated
description: >
This event is triggered when a review is updated. This can happen in one
of these cases:
- One or more attributes of a review have been updated (including a content or rating update from its author)
- A tag has been assigned or unassigned to this review on Partoo
- A review has been deleted - this could happen in two ways (see more info below):
- Permanently, by the author.
- Temporarily unavailable due to a bug in Google’s system
- If a review reappears after being temporarily unavailable
⚠️ **More info on review deletes:**
Because of a bug in Google’s system, some reviews may temporarily disappear from their data as if they were deleted, even though they were not, and then reappear later.
When a review goes missing, we cannot determine whether it was actually deleted or just affected by this bug.
We must consider this review as if it can reappear in the future. For that reason, a `review_updated` event will be sent in both cases.
Here is a sample scenario:
- September 4: A review is edited by its author.
- A `review_update` event is triggered, showing the review updated content.
- September 10: The review disappears due to the Google bug.
- Another `review_update` event is triggered, with the review state set at `deleted`
- September 15: The review becomes visible again.
- Another `review_update` is then triggered, showing the review state before the soft delete
requestBody:
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- review_updated
payload:
type: object
properties:
review:
$ref: '#/components/schemas/Review'
responses:
'200':
description: |
Return a 200 status to indicate that the event was properly received
'500':
description: >
An error in range 500-599 will trigger a retry from webhook delivery
system, up to 5 times, with an exponential backout.
> ⚠️ You may have to deal with events not received in order
security: []
reviewReplyCreated:
post:
operationId: review_reply_created
tags:
- Webhooks Events
summary: Review Reply Created
description: |
This event is triggered when a review has been replied to.
The event payload contains the event type and the reply contents.
requestBody:
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- review_reply_created
payload:
type: object
properties:
comment:
$ref: '#/components/schemas/Comment'
responses:
'200':
description: |
Return a 200 status to indicate that the event was properly received
'500':
description: >
An error in range 500-599 will trigger a retry from webhook delivery
system, up to 5 times, with an exponential backout.
> ⚠️ You may have to deal with events not received in order
security: []
reviewReplyUpdated:
post:
operationId: review_reply_updated
tags:
- Webhooks Events
summary: Review Reply Updated
description: |
This event is triggered when a review reply has been updated.
The event payload contains the event type and the reply contents.
requestBody:
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- review_reply_updated
payload:
type: object
properties:
comment:
$ref: '#/components/schemas/Comment'
responses:
'200':
description: |
Return a 200 status to indicate that the event was properly received
'500':
description: >
An error in range 500-599 will trigger a retry from webhook delivery
system, up to 5 times, with an exponential backout.
> ⚠️ You may have to deal with events not received in order
security: []
reviewReplyDeleted:
post:
operationId: review_reply_deleted
tags:
- Webhooks Events
summary: Review Reply Deleted
description: |
This event is triggered when a review reply has been deleted
The event payload contains the review reply id.
requestBody:
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- review_reply_deleted
payload:
type: object
properties:
comment_id:
$ref: '#/components/schemas/CommentId'
review_id:
$ref: '#/components/schemas/ReviewId'
responses:
'200':
description: |
Return a 200 status to indicate that the event was properly received
'500':
description: >
An error in range 500-599 will trigger a retry from webhook delivery
system, up to 5 times, with an exponential backout.
> ⚠️ You may have to deal with events not received in order
security: []
components:
parameters:
query_page:
in: query
name: page
schema:
type: integer
default: 1
description: |
Page number.
Starts at 1. Any value lower than 1 will be considered as 1.
For the number of items per page, see the `per_page` query parameter.
query_per_page_1_100:
in: query
name: per_page
schema:
type: integer
default: 30
minimum: 1
maximum: 100
description: Number of items to return per page. Currently limited to 100.
query_api_key_include_all_permissions:
in: query
name: include_all_permissions
schema:
type: boolean
default: false
description: >
Controls whether `permissions` are filtered based on what the API key's
user is actually allowed to access.
An API key can have broader permissions than its attached user's own
permissions, however they won't be taken into account unless the user
has them.
- `false` (default) — The returned `permissions` list is filtered down
with only those the user has access to.
- `true` — The returned `permissions` list is not filtered. All
permissions are included in the response, regardless of what the user
has access to.
query_filter_by_fuzzy_query_on_business:
in: query
name: query
schema:
type: string
required: false
description: Parameter to fuzzy search businesses on city, zipcode and name
query_business__in:
in: query
name: business__in
description: >-
Filter by business ids. Use a comma-separated list to provide multiple
ids.
schema:
type: array
example: >-
a1c9f37b4deca92f83b61d02,9f4e2a8c0d73b154e621bc97,c73b15e9fa42d60b3a8c21ef
items:
description: ''
$ref: '#/components/schemas/BusinessId'
query_code__in:
in: query
name: code__in
description: >-
Filter by business `code`. Use a comma-separated list to provide
multiple codes.
schema:
type: array
example: code1,code2,code3
items:
description: ''
$ref: '#/components/schemas/BusinessCode'
query_filter_by_org_id:
in: query
name: org_id
schema:
type: integer
required: false
description: >
Filter by organization ID. Only `PROVIDER` users can use this filter. If
you are not a `PROVIDER`, this will default to the ID of your
organization.
query_filter_by_groups:
in: query
name: groups
schema:
type: array
items:
type: integer
required: false
description: >
Filter by groups, using the access logic with the and/or depending on
the groups sections
See [the Groups and Sections
description](/guides/api/resources/organizations/groups)
example: 1,2,3
query_filter_by_country:
in: query
name: country
schema:
type: string
required: false
description: Filter by country - ISO 3166 alpha2 code (i.e. “FR” for France)
query_filter_by_business_name:
in: query
name: name
schema:
type: string
required: false
description: Filter by name
query_filter_by_business_status:
in: query
name: status
schema:
$ref: '#/components/schemas/BusinessStatusFilter'
query_filter_by_zipcode:
in: query
name: zipcode
schema:
type: string
required: false
description: Filter by zipcode
query_filter_by_city:
in: query
name: city
schema:
type: string
required: false
description: Filter by city
query_filter_by_business_code:
in: query
name: code
schema:
type: string
required: false
description: Filter by code
query_filter_by_business_modification_timestamp:
in: query
name: modified__gte
deprecated: false
schema:
type: number
required: false
description: Filter by modified attribute (modified >= modified_gte)
query_filter_by_business_features__in:
in: query
name: features__in
schema:
allOf:
- $ref: '#/components/schemas/FeatureEnum'
description: >
Filter businesses that have all the features provided, separated by
commas.
type: string
example: diffusion,review_management
query_filter_by_business_features__notin:
in: query
name: features__notin
schema:
allOf:
- $ref: '#/components/schemas/FeatureEnum'
description: >
Filter businesses that *do not* have all the features provided,
separated by commas.
type: string
example: diffusion,review_management
query_filter_by_business_subscription_to_review_management:
in: query
deprecated: false
name: subscribed_to_rm
schema:
type: boolean
required: false
description: >
Filter by current subscription to `review_management`.
- If `true`, only businesses subscribed to `review_management` will be
included.
- If `false`, only businesses *not* subscribed to `review_management`
will be included.
Equivalent to using `features__in=review_management`.
query_filter_by_business_subscription_to_presence_management:
in: query
deprecated: false
name: subscribed_to_pm
schema:
type: boolean
required: false
description: >
Filter by current subscription to `presence_management`.
- If `true`, only businesses subscribed to `presence_management` will be
included.
- If `false`, only businesses *not* subscribed to `presence_management`
will be included.
Equivalent to using `features__in=diffusion`.
query_filter_by_business_subscription_to_review_booster:
in: query
deprecated: false
name: subscribed_to_rb
schema:
type: boolean
required: false
description: >
Filter by current subscription to `review_booster`.
- If `true`, only businesses subscribed to `review_booster` will be
included.
- If `false`, only businesses *not* subscribed to `review_booster` will
be included.
Equivalent to using `features__in=review_invite`.
query_filter_by_business_subscription_to_messages:
in: query
deprecated: false
name: subscribed_to_bm
schema:
type: boolean
required: false
description: >
Filter by current subscription to `messages`.
- If `true`, only businesses subscribed to `messages` will be included.
- If `false`, only businesses *not* subscribed to `messages` will be
included.
Equivalent to using `features__in=messages`.
query_filter_by_business_completion_rate__gte:
in: query
name: completion_rate__gte
deprecated: false
schema:
type: integer
minimum: 0
maximum: 100
required: false
description: >-
Filter by `completion_rate` attribute (`completion_rate >=
completion_rate__gte`)
query_filter_by_business_completion_rate__lte:
in: query
name: completion_rate__lte
deprecated: false
schema:
type: integer
minimum: 0
maximum: 100
required: false
description: >-
Filter by `completion_rate` attribute (`completion_rate <=
completion_rate__lte`)
query_filter_by_business_completion_rate:
in: query
name: completion_rate
deprecated: false
schema:
type: string
enum:
- low
- mid
- high
example: low,mid
required: false
description: >-
Filter by `completion_rate` attribute. You can separate the values by a
comma, as done in the example.
query_filter_by_business_promo:
in: query
name: has_promo
deprecated: true
schema:
type: boolean
required: false
description: >
- If `true`, include only businesses having promotional offers.
- If `false`, include only businesses *not* having any promotional
offer.
query_filter_by_connected_to_gmb_location:
in: query
name: connected_to_gmb_location
schema:
type: boolean
required: false
description: >
- If `true`, only businesses currently linked to a Google location will
be included.
- If `false`, only businesses *not* linked to any Google location will
be included.
query_filter_by_connected_to_facebook_location:
in: query
name: connected_to_facebook_location
schema:
type: boolean
required: false
description: >
- If `true`, only businesses currently linked to a Facebook location
will be included.
- If `false`, only businesses *not* linked to any Facebook location will
be included.
business_id:
in: path
name: business_id
required: true
schema:
type: string
description: >
Business id.
It may be replaced by `c-{code}` where code is the store code, which
should be unique per organization. This can be used only for
`ORG_ADMIN`, `GROUP_MANAGER` and `BUSINESS_MANAGER` users.
category_name_optional:
in: query
name: category_name
required: false
schema:
type: string
example: gcid:restaurant
description: Category for which availabe attributes will be fetched.
country:
in: query
name: country
required: false
schema:
type: string
description: >
Country for which available attributes will be fetched - use ISO 3166
alpha2 code ("FR", "EN", "IT").
example: FR
category_more_hours_business:
in: query
name: category
required: false
schema:
type: string
example: gcid:restaurant
description: >-
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_more_hours_business:
in: query
name: country
required: false
schema:
type: string
description: >
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.
example: FR
path_service_id:
in: path
name: service_id
required: true
schema:
type: string
description: >
Id of the service (For creation, you can get this id by calling the [get
services suggestions
endpoint](/api-reference/google/list-google-services)).
path_org_id:
in: path
name: org_id
required: true
schema:
type: integer
description: >
Unique ID of the organization to which the resource belongs. Only
`PROVIDER` users can access resources from a different organization than
their own. If you are not a `PROVIDER`, this will default to the ID of
your organization.
query_category_country:
in: query
name: country
required: false
description: >
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.
schema:
type: string
example: FR
query_category_lang:
in: query
name: lang
required: false
schema:
$ref: '#/components/schemas/Lang'
description: >
Language to get the category name. If not given, the user's language is
used.
query_category_state:
in: query
name: state
required: false
schema:
type: string
enum:
- OK
- DEPRECATED
query_category_block_push_long:
in: query
name: block_push_long_description_on_gmb
description: >-
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)
required: false
schema:
type: boolean
query_category_search_query:
in: query
name: search_query
description: Fuzzy search on gmb_id and names translations
required: false
schema:
type: string
query_category_order_by:
in: query
name: order_by
description: |
Order results by colum. Add "-" before for ordering by descending order.
required: false
schema:
type: string
enum:
- gmb_id
- '-gmb_id'
- impacted_businesses
- '-impacted_businesses'
query_category_live__isnull:
in: query
name: live__isnull
description: |
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`
schema:
type: boolean
query_category_with_names_categories:
in: query
name: with_names
description: >
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__
required: false
schema:
type: boolean
default: false
query_category_with_countries:
in: query
name: with_countries
description: >
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__
required: false
schema:
type: boolean
default: false
query_category_return_live:
in: query
name: return_live
description: Return the corresponding live category instead of the requested category
required: false
schema:
type: boolean
default: false
query_category_with_names:
in: query
name: with_names
description: >
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__
required: false
schema:
type: boolean
default: false
PerPage:
in: query
name: per_page
schema:
type: integer
default: 30
minimum: 1
maximum: 100
description: Number of items to return per page.
Cursor:
in: query
name: cursor
schema:
type: string
description: >
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.
path_template_id:
in: path
name: template_id
required: true
schema:
type: number
description: Template id
Page:
in: query
name: page
schema:
type: integer
default: 1
minimum: 1
description: Current page number.
query_org_id:
in: query
name: org_id
schema:
type: integer
required: false
description: >
Organization ID. Only `PROVIDER` users can specify a different
organization. If not provided, defaults to your own organization.
custom_field_id:
in: path
name: custom_field_id
required: true
schema:
$ref: '#/components/schemas/CustomFieldId'
section_id:
in: path
name: section_id
required: true
schema:
$ref: '#/components/schemas/CustomFieldSectionId'
path_custom_role_api_id:
in: path
required: true
name: custom_role_api_id
schema:
type: string
description: API identifier of the custom role (`api_id`)
category_name:
in: query
name: category_name
required: true
schema:
type: string
example: gcid:restaurant
description: Category for which availabe attributes will be fetched.
lang:
in: query
name: lang
required: false
schema:
type: string
enum:
- fr
- es
- it
- en
- de
- pt
- pt-BR
description: >
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.
category_more_hours_list:
in: query
name: category
required: true
schema:
type: string
example: gcid:restaurant
description: Category for which availabe More Hour IDs will be fetched.
country_more_hours_list:
in: query
name: country
required: true
schema:
type: string
description: >
Country for which available More Hour IDs will be fetched - use ISO 3166
alpha2 code ("FR", "EN", "IT").
example: FR
lang_more_hours:
in: query
name: lang
required: false
schema:
type: string
enum:
- fr
- es
- it
- en
- de
- pt
- pt-BR
description: >
Language in which the More Hours names will be translated.
If language is not specified, by default we take the language of the
user.
google_location_id:
in: path
name: google_location_id
required: true
schema:
type: string
description: Google location unique id on Partoo
path_section_id:
in: path
name: section_id
required: true
schema:
type: integer
description: Section ID
path_group_id:
in: path
name: group_id
required: true
schema:
type: integer
description: Group ID
organization_force_delete:
in: query
name: force
required: false
schema:
$ref: '#/components/schemas/OrganizationForceDeletion'
query_post_start_datetime:
in: query
name: start_datetime
schema:
type: string
example: '2020-11-06T23:59:59'
required: false
description: >
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.
query_post_end_datetime:
in: query
name: end_datetime
schema:
type: string
example: '2020-11-06T23:59:59'
required: false
description: >
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.
query_post_summary:
in: query
name: summary
schema:
type: string
required: false
description: |
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.
query_post_state_in:
in: query
name: state__in
schema:
type: string
enum:
- live
- to_configure
- pending
- scheduled
- error
- expired
- to_validate
required: false
description: Filter Posts based on its state.
query_post_topic_type:
in: query
name: topic_type
schema:
type: string
enum:
- standard
- event
- offer
- alert
required: false
description: Filter Posts based on its type.
query_post_topic_type_in:
in: query
name: topic_type__in
schema:
type: string
enum:
- standard
- event
- offer
- alert
required: false
description: Filter Posts based on a list of different types.
path_post_id:
in: path
name: post_id
required: true
schema:
type: number
description: Post id
query_place_action_link_lang:
in: query
name: lang
required: false
schema:
$ref: '#/components/schemas/Lang'
description: >-
Preferred language for place action links. 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.
query_business__notin:
in: query
name: business__notin
description: Excludes from the request all businesses provided
schema:
type: array
items:
$ref: '#/components/schemas/BusinessId'
query_content__isnull:
in: query
name: content__isnull
description: >
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.
schema:
type: string
enum:
- 'true'
- 'false'
example: false
query_partner__in:
in: query
name: partner__in
description: Filter by publisher
schema:
type: array
items:
$ref: '#/components/schemas/ReviewPublisherLabel'
example: google_my_business,facebook
query_gmb_rating__in:
in: query
name: gmb_rating__in
description: |
Filter only by Google ratings
schema:
type: array
items:
type: number
enum:
- 1
- 2
- 3
- 4
- 5
example: 4,5
query_tripadvisor_rating__in:
in: query
name: tripadvisor_rating__in
description: |
Filter only by Tripadvisor ratings
schema:
type: array
items:
type: number
enum:
- 1
- 2
- 3
- 4
- 5
example: 1,2
query_recommended__in:
in: query
name: recommended__in
description: |
Filter only by Facebook recommendation
schema:
type: array
items:
type: boolean
enum:
- true
- false
example: false
query_review_update_date__gte:
in: query
name: update_date__gte
description: >
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.
schema:
type: string
format: datetime
example: '2017-08-01T00:00:00'
query_review_update_date__lte:
in: query
name: update_date__lte
description: >
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.
schema:
type: string
format: datetime
example: '2017-08-02T00:00:00'
query_review_state:
in: query
name: state__in
description: |
Filter by state. Comma-separated list of review states.
schema:
type: array
items:
$ref: '#/components/schemas/ReviewState'
example: treated,not_treated
query_review_state__notin:
in: query
name: state__notin
description: >
Exclude reviews in the given states. Comma-separated list of review
states.
schema:
type: array
items:
$ref: '#/components/schemas/ReviewState'
example: deleted
query_tag_label_in:
in: query
name: tag_label__in
description: >
Filter by Tag label
Will partially match given labels (ie `foo` will match reviews with tag
`food`)
schema:
type: array
items:
$ref: '#/components/schemas/TagLabel'
example: food,drink
query_review_without_tag:
in: query
name: without_tag
description: |
Filter only reviews without tags
schema:
type: boolean
example: true
query_keywords:
in: query
name: keywords
description: >
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.
schema:
type: array
items:
type: string
example: bonjour,good+service
query_with_media_links:
in: query
name: with_media_links
description: >
When set to true, enriches review responses with associated customer
media URLs from Google My Business.
The media links will appear in the field __media_links__ as an array of
strings.
- If `with_media_links` is **false** (default): __media_links__ will be
an empty array `[]`
- If `with_media_links` is **true**:
- Reviews with associated photos: __media_links__ will contain Google photo URLs
- Reviews without photos: __media_links__ will be an empty array `[]`
required: false
schema:
type: boolean
default: false
example: true
review_query_order_by:
in: query
name: order_by
schema:
type: string
enum:
- update_date
- '-update_date'
example: update_date
description: |
A `-` sign in front of the value indicates a descending order.
query_positive_template:
in: query
name: positive
description: >-
Filter on templates made to answer positive reviews (ex from 4 to 5
stars on gmb).
required: false
schema:
type: boolean
query_neutral_template:
in: query
name: neutral
description: Filter on templates made to answer neutral reviews (ex 3 stars on gmb).
required: false
schema:
type: boolean
query_negative_template:
in: query
name: negative
description: >-
Filter on templates made to answer negative reviews (ex from 1 to 2
stars on gmb).
required: false
schema:
type: boolean
query_language__in:
in: query
name: language__in
description: Filter on templates in the specified languages.
required: false
schema:
type: array
items:
$ref: '#/components/schemas/Lang'
example: fr,it
query_title_query:
in: query
name: title_query
schema:
type: string
required: false
description: Filter on templates based on their title
query_text_query:
in: query
name: text_query
schema:
type: string
required: false
description: Filter on templates based on their text
query_metrics_presence:
in: query
name: metrics
required: true
description: |
List of analytics to return.
At least one in that list.
schema:
type: 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
query_dimensions_presence:
in: query
name: dimensions
required: false
description: >
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.
schema:
type: string
enum:
- business
- day
- week
- month
- year
query_order_by_presence:
in: query
name: order_by
required: false
description: >
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
schema:
type: string
enum:
-