Users

Getting details

Retrieve all information about a given user.

Request URL:

GET /api/v2/user/{user_id}?api_key={my_api_key}

Query parameters:

Parameter Type Required Default Description
api_key string True None Your API key
user_id string True None Id of the user
display_business_ids True|False False True The endpoint won’t return the business_ids when the value is False

JSON response:

{
    "id"                : "user id (string)",
    "status    "        : "status (active/invited) (string)",
    "first_name"        : "first name (string)",
    "last_name"         : "last name (string)",
    "business_ids"      : "business ids the user has WRITE permission on (list<string>)",
    "org_id"            : "id of the org the user belongs to (READ permission)",
    "phone"             : "phone number (string)",
    "role"              : "the role of the user in the application",
    "email"             : "email (string)"
}

Getting my information

Retrieve all information about the user you are using to make API calls.

Request URL:

GET /api/v2/user/me?api_key={my_api_key}

Query parameters:

Parameter Type Required Default Description
api_key string True None Your API key
display_business_ids True|False False True The endpoint won’t return the business_ids when the value is False

JSON response:

{
    "id"                : "user id (string)",
    "status    "        : "status (active/invited) (string)",
    "first_name"        : "first name (string)",
    "last_name"         : "last name (string)",
    "business_ids"      : "business ids the user has WRITE permission on (list<string>)",
    "org_id"            : "id of the org the user belongs to (READ permission)",
    "phone"             : "phone number (string)",
    "role"              : "the role of the user in the application",
    "email"             : "email (string)"
}

Searching

The user/search/ resource lets you search for users using filters.

Request URL:

GET /api/v2/user/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 users by org id
last_name string False None Filter users by last name
email string False None Filter users by email
status string False None Filter users by status
page int False 1 Page number. 30 results per page
display_business_ids True|False False True The endpoint won’t return the business_ids when the value is False
query string False None To perform a fuzzy search on user

JSON response:

{
    "page"            : "page number (int)",
    "max_page"        : "last page number (int)",
    "count"           : "total number of businesses found (int)",
    "users": [
        {
            "id"                : "user id (string)",
            "status"            : "status (active/invited) (string)",
            "first_name"        : "first name (string)",
            "last_name"         : "last name (string)",
            "business_ids"      : "business ids the user administer (list<string>)",
            "phone"             : "phone number (string)",
            "email"             : "email (string)"
        }
    ]
}

Creating

Request URL:

POST /api/v2/user

Request JSON Body:

{
    "api_key": "you_api_key",
    "status" : "status (active/invited) (string)",
    "email": "email@partoo.fr",
    "first_name": "Noël",
    "last_name": "Flantier",
    "business_ids": [],
    "org_id": 12345,
    "lang": "fr",
    "role": "BUSINESS_MANAGER",
    "send_invitation": "True",
    "phone": "+33612131415"
}

Request parameters:

Parameter Type Required Default Description
api_key string True   Your API key
email string True   Email
first_name string True   First name
last_name string True   Last name
lang string False   user lang used in emails and in the interface
status string False active if user status is ‘active’, you have to set a password. If a user status is ‘invited’, the user will receive an email with a link to his page, asking him to set up a password to activate his account.
role string False BUSINESS_MANAGER Use role possible values PROVIDER, BUSINESS_MANAGER, ORG_ADMIN
org_id int False   id of the org the user belongs to (he has READ access to all its businesses)
password string False random string Password of the user (at least 6 chars long). Disabled if status is invited (the user will have to set up himself the password)
send_invitation “True”|”False” False “False” Send an invitation email when set to “True”
business_ids list<string> False [] ids of the businesses the user can WRITE
phone string False   Phone number of the user

JSON response:

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

If the email is duplicated, the following error is returned with status 400:

{
    "errors": {
        "json": {
            "email": "rene.cotty@partoo.fr already exists in db"
        }
    }
}

Updating

Request URL:

POST /api/v2/user/{user_id}

Request JSON Body:

{
    "api_key": "you_api_key",
    "status" : "status (active/invited) (string)",
    "email": "email@partoo.fr",
    "first_name": "Noël",
    "last_name": "Flantier",
    "business_ids": [],
    "org_id": 12345,
    "lang": "fr",
    "phone": "+33612131415"
}

Request parameters:

Parameter Type Required Default Description
api_key string True   Your API key
user_id int True   id of the user to update
org_id int False   id of the org the user belongs to (he has READ access to all its businesses)
email string False   email
lang string False   user lang used in emails and in the interface
password string False None change user password to given value if indicated
status string False active if user status is ‘active’, a password needs to bet set. If a user status is ‘invited’, the user will receive an email with a link to his page, asking him to set up a password to activate his account.
role string False BUSINESS_MANAGER Use role possible values PROVIDER, BUSINESS_MANAGER, ORG_ADMIN
first_name string False   first name
last_name string False   last name
business_ids list<string> False   ids of the businesses the user can WRITE
phone string False   Phone number of the user

JSON response:

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

Deleting

Request URL:

DELETE /api/v2/user/{user_id}

JSON response:

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

Stats

The user/stats resource gives you details about the status of the users of a manager.

Request URL:

GET /api/v2/user/stats?api_key={my_api_key}

Request parameters:

Parameter Type Required Default Description
api_key string True None Your API key

JSON response:

{
    "count"            : "total users count (int)",
    "invited_count"    : "invited users count (int)",
    "activate_count"   : "active users count (int)"
}

Re-invite

The api/v2/user/{user_id}/invite resource triggers a new invitation email. The email can only be sent once every 5 minutes to user with the ‘invited’ status.

Request URL:

POST /api/v2/user/{userId}/invite?api_key={my_api_key}

Request parameters:

Parameter Type Required Default Description
user_id int True   id of the user to re-invite
api_key string True None Your API key

JSON response:

{
    "status": "success",
}