Businesses

Getting details

Retrieve all information about a given business.

Request URL:

GET /api/v2/business/{business_id}?api_key={my_api_key}

Query parameters:

Parameter Type Required Description
api_key string True Your API key
business_id string True Id of the business

JSON response:

{
    "id"                : "business id (string)",
    "code"              : "business owners sometimes have their own ids to identify their businesses (string)",
    "status"            : "status of the business 'open' or 'closed' (string)",
    "org_id"            : "organization id (every client is identified by a unique id on Partoo) (int)",
    "name"              : "name of the business (string)",
    "created"           : "timestamp when the business was created (int)",
    "modified"          : "timestamp when the business was last modified (int)",
    "address"           : "address of the business (string)",
    "address_details": {
        "number"              : "street number (e.g. '13') (string)",
        "number_supplement"   : "'bis' or 'ter' (e.g. 'bis') (string)",
        "street_type"         : "type of street (e.g. 'rue')",
        "street_name"         : "name of the street (e.g. 'du Rosier')"
    },
    "address2"          : "address supplement (string)",
    "city"              : "city (string)",
    "zipcode"           : "zipcode (string)",
    "region"            : "region (string)",
    "country"           : "country (string) - ISO 3166 alpha2 code",
    "lang"              : "language (string) - ISO 639-1 code",
    "lat"               : "latitude (float)",
    "long"              : "longitude (float)",
    "siret"             : "SIRET code (string)",
    "categories"        : "categories the business belong to (list of strings)",
    "description_short" : "short description (200 characters max) of the business activity (string)",
    "description_long"  : "long description (1000 characters max) of the business activity (string)",
    "website_url"       : "URL to the website of the business (string)",
    "facebook_url"      : "URL to the Facebook page (string)",
    "twitter_url"       : "URL to the Twitter feed (string)",
    "logo_url"          : "URL to the business logo (string)",
    "photos": {
        "primary"   : "URL to the picture that the business owner want to show primarily (string)",
        "secondary" : ["URLs to secondary pictures (list of strings)"]
    },
    "videos"        : ["URLs to videos (list of strings)"],
    "contacts": [
        {
            "name"            : "name of the contact (string)",
            "email"           : "email of the contact (string)",
            "phone_numbers"   : "phone numbers of the contact (list of strings)"
        }
    ],
    "open_hours": {
        "monday"     : ["Monday open hours (list of strings like ['07:30-10:00', '13:30-17:30'])"],
        "tuesday"    : ["Tuesday open hours (list of strings)"],
        "wednesday"  : ["Wednesday open hours (list of strings)"],
        "thursday"   : ["Thursday open hours (list of strings)"],
        "friday"     : ["Friday open hours (list of strings)"],
        "saturday"   : ["Saturday open hours (list of strings)"],
        "sunday"     : ["Sunday open hours (list of strings)"]
    },
    "human_friendly_open_hours": {
        "monday"     : ["Monday open hours (list of strings like ['07:30-10:00', '13:30-17:30'])"],
        "tuesday"    : ["Tuesday open hours (list of strings)"],
        "wednesday"  : ["Wednesday open hours (list of strings)"],
        "thursday"   : ["Thursday open hours (list of strings)"],
        "friday"     : ["Friday open hours (list of strings)"],
        "saturday"   : ["Saturday open hours (list of strings)"],
        "sunday"     : ["Sunday open hours (list of strings)"]
    },
    "specific_hours"  : {
        "open": [
            {
                "starts_at": "Start date of specific open hours (string like <YYYY>-<MM>-<DD>)",
                "ends_at": "End date of specific open hours (string like <YYYY>-<MM>-<DD>)",
                "open_hours": "list of strings like ['07:30-10:00', '13:30-17:30']"
            }
        ],
        "close": [
            {
                "starts_at": "Start date of specific closed days (string like <YYYY>-<MM>-<DD>)",
                "ends_at": "End date of specific closed days (string like <YYYY>-<MM>-<DD>)"
            }
        ]
    },
    "price_range": {
        "max"                 : "upper price in cents (int)",
        "min"                 : "lower price in cents (int)"
    },
    "promos"                  : "list of on-going promotional offer objects (see below) (list)",
    "news"                    : "list of news published by the business (see below) (list)"
}

Promotional offers:

{
    "_id"                        : "id of the promotional offer (string)",
    "title"                      : "title of the promotional offer (string)",
    "description"                : "description of the promotional offer (string)",
    "terms_of_use"               : "terms_of_use of the promotional offer (string)",
    "additional_informations"    : "additional_informations of the promotional offer (string)",
    "created"                    : "timestamp when the promotional offer was created (epoch)",
    "begin"                      : "timestamp when the offer begins (int)",
    "end"                        : "timestamp when the offer ends (int)",
    "images"                     : "images associated to the promotional offer (list of urls)",
    "client_offer_url"           : "url of the cleint's promotional offer",
    "promo_url"                  : "website of the promotional offer (url)"
}

News:

{
    "title"          : "title of the promotional offer (string)",
    "description"    : "description of the promotional offer (string)",
    "created"        : "timestamp when the news was published (int)"
}

Searching

The business/search/ resource lets you search for businesses using filters. This resource also enables you to crawl the entire businesses database when no filter is applied.

Request URL:

GET /api/v2/business/search?api_key={my_api_key}

Request parameters:

Parameter Type Required Default Description
api_key string True None Your API key
org_id int False None Filter businesses by org id
name string False None Filter businesses by name
has_promo string False false Retrieve only businesses having promotional offers
page int False 1 Page number. 30 results per page.
country string False None Filter businesses by country - use ISO 3166 alpha2 code (i.e. use “FR” for France)
status string False ‘open’ Filter businesses by status
timestamp int False 0 Filter businesses by modified attribute (modified >= timestamp)
zipcode string False None Filter businesses by zipcode
city string False None Filter businesses by city
code string False None Filter businesses by code
subscribed_to_rm True|False False None Filter businesses by current subscription to review_management
subscribed_to_pm True|False False None Filter businesses by current subscription to presence_management
google_location_id True|False False None Filter businesses by current link to a gmb business
query string False ‘’ Parameter to fuzzy search businesses on city, zipcode and name

JSON response:

{
    "page"            : "page number (int)",
    "max_page"        : "last page number (int)",
    "count"           : "total number of businesses found (int)",
    "businesses": [
                    "list of business objects (see the business details resource)"
    ]
}

Creating

Request URL:

POST /api/v2/business

JSON Body

{
    "api_key": "your api key",
    "name": "SCEP",
    "country": "FR",
    "zipcode": "75017",
    "city": "Paris",
    "address_details": {
        "number": "10",
        "number_supplement": "ter",
        "street_type": "rue",
        "street_name": "du poulet"
    },
    "categories": ["57def0b5b12ff65e069c34f6"],
    "contacts": [{
        "name"            : "Noël",
        "email"           : "noel@flantier.com",
        "phone_numbers"   : ["+33612131415"]
    }]
}

Response:

{
    "status": "success",
    "id": "5409c35b97aac999d8c267371"
}

Query parameters:

Parameter Type Required Default Status Description
api_key string True   stable Your API key
name string True   stable Name of the business
zipcode string True   stable Zip code
city string True   stable City
country string True   stable Country - ISO 3166 alpha2 code
address_details AddressDetails True   stable Address details of the Business
categories list(string) True   stable Categories ids the business belong to
contacts list(Contact) True   stable Physical contacts for the business
org_id int False   stable Organisation id
code string False auto gen stable Business client identifier
status string False open stable Status of the business ‘open’, ‘closed’, ‘definitely_closed’
address2 string False   stable Address supplement
region string False   stable Region
lat float False   stable Latitude
long float False   stable Longitude
national_identification_number string False   stable National identification number
description_short string False   stable Short description
description_long string False   stable Long description
website_url url False   stable URL to the website of the business
facebook_url url False   stable URL to the Facebook page
twitter_url url False   stable URL to the Twitter feed
photos Photos False   stable Business Photos
open_hours OpenHours False   stable Business open hours
specific_hours SpecificHours False   stable Business specific opening hours (e.g. on bank holidays)
videos list(url) False   deprecated URLs to videos
promos list(Promo) False   deprecated List of on-going promotional offer
news list(News) False   deprecated List of news published by the business

Photos objects

Parameter Type Required Default Description
primary url False   URL to the picture that the business owner want to show primarily (string)
secondary list(url) False   URLs to secondary pictures (list of strings)
LOGO url False   Logo URL
{
    "primary"   : "http://partoo.fr/static/photo.jpg",
    "secondary" : ["http://partoo.fr/static/photo_3.jpg", "http://partoo.fr/static/photo_2.jpg" ],
    "LOGO"      : "http://partoo.fr/static/logo.jpg"
}

AddressDetails objects

Parameter Type Required Default Description
number string False   Street number e.g. “13”
number_supplement string False   Street number supplement e.g. “bis” or “ter”
street_type string False   Type of street e.g. “rue”
street_name string True   Name of the street (e.g. “du Rosier”)
{
    "number"              : "13",
    "number_supplement"   : "bis",
    "street_type"         : "rue",
    "street_name"         : "du Rosier"
}

Contacts objects

Parameter Type Required Default Description
name string False   Full name of the contact
email email False   Email of the contact
phone_numbers list(string) False   Phone numbers of the contact
{
    "name"            : "Noël",
    "email"           : "Flantier",
    "phone_numbers"   : ["+33612131415"]
}

OpenHours objects

Parameter Type Required Default Description
monday list(string) False [] Monday open hours
tuesday list(string) False [] Tuesday open hours
wednesday list(string) False [] Wednesday open hours
thursday list(string) False [] Thursday open hours
friday list(string) False [] Friday open hours
saturday list(string) False [] Saturday open hours
sunday list(string) False [] Sunday open hours
{
    "monday"     : ["07:30-10:00", "13:30-17:30"],
    "tuesday"    : ["07:30-10:00", "13:30-17:30"],
    "wednesday"  : ["07:30-10:00", "13:30-17:30"],
    "thursday"   : ["07:30-10:00", "13:30-17:30"],
    "friday"     : ["07:30-10:00", "13:30-17:30"],
    "saturday"   : ["07:30-12:00"],
    "sunday"     : []
}

SpecificHours objects

Parameter Type Required Default Description
starts_at string True   Start date for specific opening/closing days (date inclusive)
ends_at string True   End date for specific opening/closing days (date inclusive)
open_hours list(string) True [] Open hours on specific opening days
{
    "open": [
        {
            "starts_at":  "2018-12-24",
            "ends_at":  "2018-12-24",
            "open_hours": ["07:30-10:00", "13:30-17:30"]
        }
    ],
    "close": [
        {
            "starts_at":  "2018-12-25",
            "ends_at":  "2018-12-25"
        }
    ]

}

Promo objects

Warning : This object is deprecated and will be removed in the next major version of the API.

Parameter Type Required Default Description
title string True   Title
description string True   Description
terms_of_use string False   Term of use
additional_informations string False   Additional informations
begin int True   Time and Date when the offer begins
end int True   Time and Date when the offer ends
images list(url) False   Images to be displayed along with the promotional offer
client_offer_url url False   Url of the offer
promo_url url False   Url of the website
{
    "title"                      : "Reduction sur les jokaris",
    "description"                : "- 25% sur les jokaris (1)",
    "terms_of_use"               : "(1) Uniquement valable cet été au Caire",
    "additional_informations"    : "C'est mauvais Jack!",
    "begin"                      : 1507801710,
    "end"                        : 1508060909,
    "images"                     : ["http://partoo.fr/images/promo.jpg"],
    "client_offer_url"           : "https://partoo.fr/promo/1123321",
    "promo_url"                  : "https://partoo.fr"
}

News objects

Warning : This object is deprecated and will be removed in the next major version of the API.

Parameter Type Required Default Description
title string True   title of the promotional offer
description string True   description of the promotional offer
{
    "title"          :  "Les attraits du présence management",
    "description"    :  "Partoo se place comme une des solutions d'avenir en matière de Présence management"
}

Updating

Update a given business.

None of the parameters in the update business endpoint is necessary. If a parameter is missing, it will be ignored by the system, that is to say it will remain unchanged. We made this choice to enable partial update.

Request URL:

POST /api/v2/business/{business_id}

JSON Body

{
    "api_key": "you_api_key",
    "name": "SCEP du Caire",
    "property": "value"
}

Query parameters:

Parameter Type Required Default Status Description
api_key string True   stable Your API key
business_id string False   stable Id of the business
org_id string False   stable Organisation id
name string False   stable Name of the business
address_details AddressDetails False   stable Address details of the Business
categories list(string) False   stable Categories the business belong to
contacts list(Contact) False   stable Physical contacts for the business
country string False   stable Country - ISO 3166 alpha2 code
city string False   stable City
zipcode string False   stable Zipcode
code string False auto gen stale Business client identifier
status string False open stable Status of the business ‘open’, ‘closed’, ‘definitely_closed’
address2 string False   stable Address supplement
region string False   stable Region
lang string False   stable Language - ISO 639-1 code
lat float False   stable Latitude
long float False   stable Longitude
national_identification_number string False   stable National identification number
description_short string False   stable Short description
description_long string False   stable Long description
website_url url False   stable URL to the website of the business
facebook_url url False   stable URL to the Facebook page
twitter_url url False   stable URL to the Twitter feed
photos Photos False   stable Business Photos
open_hours OpenHours False   stable Business open hours
specific_hours SpecificHours False   stable Business sppecific opening hours (e.g. on bank holidays)
videos list(url) False   deprecated URLs to videos
promos list(Promo) False   deprecated List of on-going promotional offer
news list(News) False   deprecated List of news published by the business

Response:

{
    "status": "success",
    "id": "5409c35b97aac999d8c267371"
}

Deleting

Delete a given business. You must be an ORG_ADMIN to perform this action.

Request URL:

DELETE /api/v2/business/{business_id}

JSON Body

{
    "api_key": "you_api_key",
}

Response:

{
    "status": "success",
    "id": "5409c35b97aac999d8c267371"
}

Actions on businesses

List a given business subscriptions.

Request URL:

GET /api/v2/business/{business_id}/subscription

JSON Body

{
    "api_key": "you_api_key"
}

Response:

{
    "presence_management": {
        "status": "active"
        "subscription_date": 1540628702
    },
    "review_management": {
        "status": "inactive"
        "canceling_date": 1440628702
    }
}

Subscribe a business to a product

Request URL:

POST /api/v2/business/{business_id}/subscribe

JSON Body

{
    "api_key": "you_api_key",
    "subscription_date": 1540628702,
    "products": ["presence_management"],
    "plan": "any string that define your offer"
}

Query parameters:

Parameter Type Required Default Description
api_key string True   Your API key
products list[string] True   Product(s) to subscribe to
subscription_date int False now Date of the start of the subscription

Response:

{
    "presence_management": {
        "status": "active",
        "subscription_date": 1540628702
    },
    "review_management": {
        "status": "inactive",
        "canceling_date": 1440628702
    }
}

Unsubscribe a business to a product

Request URL:

POST /api/v2/business/{business_id}/unsubscribe

JSON Body

{
    "api_key": "you_api_key",
    "canceling_date": 1440628702,
    "products": ["review_management"]
}

Query parameters:

Parameter Type Required Default Description
api_key string True   Your API key
products list[string] True   Product(s) to subscribe to
canceling_date int False now Date of the end of the subscription (might be in the future)

Response:

{
    "presence_management": {
        "status": "active",
        "subscription_date": 1540628702
    },
    "review_management": {
        "status": "inactive",
        "canceling_date": 1440628702
    }
}

Get integration status

Display the integration status on the different partners for a given business.

Request URL:

GET /api/v2/business/{business_id}/integration_status

Query parameters:

Parameter Type Required Description
api_key string True Your API key
business_id string True Id of the business

Response:

{
    "google_my_business": {
        "url": "https://maps.google.com/maps?cid=10328155080888285809",
        "status": "PENDING",
        "timestamp": "2019-03-01T09:43:36"
    },
    "apple": {},
    "le118000": {},
    "les_horaires": {},
    "wemap": {},
    "here": {},
    "annuaire": {},
    "foursquare": {},
    "facebook": {},
    "justacote": {},
    "navmii": {},
    "dismoiou": {},
    "bing_fr": {}
}

The possible values for status are:

  • PENDING: the data push is waiting to be executed by one of our worker
  • SUCCESS: the business was either successly updated/created or deleted
  • FIELD_ERROR: one the business field blocked the update on partner
  • FIELD_REJECTED: the business was partially updated. Some fields rejected because they don’t meet partner requirements
  • DUPLICATED_BUSINESSES: the business is a duplicate of an existing partner on partner
  • ERROR: there was an unexpected error during udpate, Partoo team must deal with it

Get partner urls

Request URL:

GET /api/v2/business/{business_id}/partner_urls

Query parameters:

Parameter Type Required Description
api_key string True Your API key
business_id string True Id of the business

Response:

{
    "apple": "http://maps.apple.com/?q=Partoo&sll=48.898204,2.378016&z=10",
    "le118000": "http://www.118000.fr/e_C0063781595",
    "les_horaires": "",
    "wemap": "",
    "here": "",
    "google_my_business": "https://maps.google.com/maps?cid=10328155080888285809",
    "annuaire": "https://annuaire.laposte.fr/programmeur-informatique/partoo-80342540400024/",
    "foursquare": "https://foursquare.com/v/583b7123de0cbc3f33910edb",
    "facebook": "",
    "justacote": "https://www.justacote.com/paris-75019/autre/partoo-2669690.htm",
    "navmii": "http://livepoi.navmii.com/p/view/f562102e-e2cd-49da-b0ae-ab5b56607ecb",
    "dismoiou": "http://dismoiou.fr/p/A3B82F10-285F-4076-BD76-02DC0583D3CE",
    "bing_fr": ""
}

Get additional data

Lets a business access it’s additional_data.

Request URL:

GET /api/v2/business/{business_id}/additional_data

Query parameters:

Parameter Type Required Description
api_key string True Your API key
business_id string True Id of the business

Response:

{
    "client_key_1": "client_value_1",
    "client_key_2": "client_value_2",
    "client_key_10": "client_value_10",
}

Set additional data

Lets a business set it’s additional_data.

Request URL:

POST /api/v2/business/{business_id}/additional_data

JSON Body

No nested json, no arrays, not more than 10 keys.

{
    "client_key_1": "client_value_1",
    "client_key_2": "client_value_2",
    "client_key_10": "client_value_10",
}

Query parameters:

Parameter Type Required Description
api_key string True Your API key
business_id string True Id of the business

Response:

{
    "status": "success",
    "id": "5409c35b97aac999d8c267371"
}