• About & Auth.
  • Access model
  • Using the API Key
  • Using a JWT token
  • Using DIGEST
• Endpoints
  • Ping
    • GET /ping
  • Account Creation Request Tokens
    • POST /account_creation_request_tokens
  • Account Creation Tokens
    • POST /account_creation_tokens/send-by-push
    • POST /account_creation_tokens/using-account-creation-request-token
    • POST /account_creation_tokens
  • Auth Tokens
    • POST /accounts/auth_token
    • GET /accounts/auth_token/{auth_token}/attach
  • Accounts
    • POST /accounts/public
    • POST /accounts/with-account-creation-token
    • GET /accounts/{sip}/info
    • GET /accounts/{phone}/info-by-phone
    • POST /accounts/recover-by-phone
    • GET /accounts/{sip}/recover/{recover_key}
    • POST /accounts/{sip}/activate/email
    • POST /accounts/{sip}/activate/phone
    • GET /accounts/me/api_key/{auth_token}
    • GET /accounts/me/api_key
    • GET /accounts/me
    • GET /accounts/me/provision
    • DELETE /accounts/me
    • POST /accounts/me/password
    • POST /accounts
    • PUT /accounts/{id}
    • GET /accounts
    • GET /accounts/{id}
    • GET /accounts/{sip}/search
    • GET /accounts/{email}/search-by-email
    • DELETE /accounts/{id}
    • POST /accounts/{id}/activate
    • POST /accounts/{id}/deactivate
    • POST /accounts/{id}/block
    • POST /accounts/{id}/unblock
    • GET /accounts/{id}/provision
  • Accounts email
    • POST /accounts/me/email/request
  • Accounts phone number
    • POST /accounts/me/phone/request
    • POST /accounts/me/phone
  • Accounts devices
    • GET /accounts/me/devices
    • DELETE /accounts/me/devices/{uuid}
  • Account contacts
    • GET /accounts/me/contacts
    • GET /accounts/me/contacts/{sip}
  • Contacts
    • GET /accounts/{id}/contacts
    • POST /accounts/{id}/contacts/{contact_id}
    • DELETE /accounts/{id}/contacts/{contact_id}
  • Dictionary
    • GET /accounts/{id}/dictionary
    • POST /accounts/{id}/dictionary/{key}
    • DELETE /accounts/{id}/dictionary/{key}
  • Account Actions
    • GET /accounts/{id}/actions
    • GET /accounts/{id}/actions/{action_id}
    • POST /accounts/{id}/actions/
    • PUT /accounts/{id}/actions/{action_id}
    • DELETE /accounts/{id}/actions/{action_id}
  • Contacts Lists
    • GET /contacts_lists
    • GET /contacts_lists/{id}
    • POST /contacts_lists
    • PUT /contacts_lists/{id}
    • DELETE /contacts_lists/{id}
    • POST /contacts_lists/{contacts_list_id}/contacts/{contact_id}
    • DELETE /contacts_lists/{contacts_list_id}/contacts/{contact_id}
    • POST /accounts/{id}/contacts_lists/{contacts_list_id}
    • DELETE /accounts/{id}/contacts_lists/{contacts_list_id}
  • Account Types
    • GET /account_types
    • GET /account_types/{id}
    • POST /account_types
    • PUT /account_types/{id}
    • DELETE /account_types/{id}
    • POST /accounts/{id}/types/{type_id}
    • DELETE /accounts/{id}/contacts/{type_id}
  • Messages
    • POST /messages
  • Statistics
    • POST /statistics/messages
    • PATCH /statistics/messages/{message_id}/to/{to}/devices/{device_id}
    • POST /statistics/calls
    • PATCH /statistics/calls/{call_id}/devices/{device_id}
    • PATCH /statistics/calls/{call_id}
• Non-API Endpoints
  • Contacts list
    • GET /contacts/vcard
    • GET /contacts/vcard/{sip}

About & Auth.¶

An API to deal with the Flexisip server.

The API is available under /api

A content-type and accept HTTP headers are REQUIRED to use the API properly

> GET /api/{endpoint}
> content-type: application/json
> accept: application/json

> GET /api/{endpoint}
> x-api-key: {your-api-key}
> …

> GET /api/{endpoint}
> Cookie: x-api-key={your-api-key}
> …

> GET /api/{endpoint}
> Authorization: Bearer {your-jwt-token}
> …

> GET /api/{restricted-endpoint}
> from: sip:foobar@sip.example.org
> …

< HTTP 401
< content-type: application/json
< www-authenticate: Digest realm=test,qop=auth,algorithm=MD5,nonce="{nonce}",opaque="{opaque}"
< www-authenticate: Digest realm=test,qop=auth,algorithm=SHA-256,nonce="{nonce}",opaque="{opaque}"

Endpoints¶

Ping¶

GET /ping¶

Public

Returns pong

Account Creation Request Tokens¶

An account_creation_request_token is a unique token that can be validated and then used to generate a valid account_creation_token.

POST /account_creation_request_tokens¶

Public

Create and return an account_creation_request_token that should then be validated to be used.

Account Creation Tokens¶

An account_creation_token is a unique token that allow the creation or the validation of a unique account.

POST /account_creation_tokens/send-by-push¶

Public

Create and send an account_creation_token using a push notification to the device. Return 403 if a token was already sent, or if the tokens limit is reached for this device. Return 503 if the token was not successfully sent.

JSON parameters:

• pn_provider the push notification provider
• pn_param the push notification parameter
• pn_prid the push notification unique id

POST /account_creation_tokens/using-account-creation-request-token¶

Public

Create an account_creation_token using an account_creation_request_token. Return an account_creation_token. Return 404 if the account_creation_request_token provided is not valid or expired otherwise.

JSON parameters:

• account_creation_request_token required

POST /account_creation_tokens¶

Admin

Create and return an account_creation_token.

Auth Tokens¶

POST /accounts/auth_token¶

Public

Generate an auth_token. To attach the generated token to an account see auth_token attachement endpoint.

Return the auth_token object.

GET /accounts/auth_token/{auth_token}/attach¶

User

Attach a publicly generated authentication token to the currently authenticated account.

Return 404 if the token is non existing or invalid.

Accounts¶

POST /accounts/public¶

Deprecated Public Unsecure endpoint

Create an account. Return 422 if the parameters are invalid. Send an email with the activation key if email is set, send an SMS otherwise.

JSON parameters:

• username required if phone not set, unique username, minimum 6 characters
• password required minimum 6 characters
• algorithm required, values can be SHA-256 or MD5
• domain if not set the value is enforced to the default registration domain set in the global configuration
• email optional if phone set, an email, set an email to the account, must be unique if ACCOUNT_EMAIL_UNIQUE is set to true
• phone required if username not set, optional if email set, a phone number, set a phone number to the account
• account_creation_token the unique account_creation_token

POST /accounts/with-account-creation-token¶

Public

Create an account using an account_creation_token. Return 422 if the parameters are invalid or if the token is expired.

JSON parameters:

• username unique username, minimum 6 characters
• password required minimum 6 characters
• algorithm required, values can be SHA-256 or MD5
• account_creation_token the unique account_creation_token
• dtmf_protocol optional, values must be sipinfo, sipmessage or rfc2833

GET /accounts/{sip}/info¶

Public

Retrieve public information about the account. Return 404 if the account doesn't exists.

GET /accounts/{phone}/info-by-phone¶

Deprecated Public Unsecure endpoint

Retrieve public information about the account. Return 404 if the account doesn't exists.

Return phone: true if the returned account has a phone number.

POST /accounts/recover-by-phone¶

Deprecated Public Unsecure endpoint

Send a SMS with a recovery PIN code to the phone number provided. Return 404 if the account doesn't exists.

Can only be used once, a new recover_key need to be requested to be called again.

JSON parameters:

• phone required the phone number to send the SMS to
• account_creation_token the unique account_creation_token

GET /accounts/{sip}/recover/{recover_key}¶

Deprecated Public Unsecure endpoint

Activate the account if the correct recover_key is provided.

The sip parameter can be the default SIP account or the phone based one.

Return the account information (including the hashed password) if valid.

Return 404 if the account doesn't exists.

POST /accounts/{sip}/activate/email¶

Deprecated Public

Use POST /accounts/me/email/request instead.

Activate an account using a secret code received by email. Return 404 if the account doesn't exists or if the code is incorrect, the validated account otherwise.

JSON parameters:

• confirmation_key the confirmation key

POST /accounts/{sip}/activate/phone¶

Deprecated Public

Use POST /accounts/me/phone/request instead.

Activate an account using a pin code received by phone. Return 404 if the account doesn't exists or if the code is incorrect, the validated account otherwise.

JSON parameters:

• confirmation_key the PIN code

GET /accounts/me/api_key/{auth_token}¶

Public

Generate and retrieve a fresh API Key from an auth_token. The auth_token must be attached to an existing account, see auth_token attachement endpoint to do so.

Return 404 if the token is invalid or not attached.

This endpoint is also setting the API Key as a Cookie.

GET /accounts/me/api_key¶

User

Generate and retrieve a fresh API Key. This endpoint is also setting the API Key as a Cookie.

GET /accounts/me¶

User

Retrieve the account information.

GET /accounts/me/provision¶

User

Provision the account by generating a fresh provisioning_token.

Return the account object.

DELETE /accounts/me¶

User

Delete the account.

POST /accounts/me/password¶

User

Change the account password.

JSON parameters:

• algorithm required, values can be SHA-256 or MD5
• old_password required if the password is already set, the old password
• password required, the new password

POST /accounts¶

Admin

To create an account directly from the API. Deprecated If activated is set to false a random generated confirmation_key and provisioning_token will be returned to allow further activation using the public endpoints and provision the account. Check confirmation_key_expires to also set an expiration date on that confirmation_key.

JSON parameters:

• username unique username, minimum 6 characters
• password required minimum 6 characters
• algorithm required, values can be SHA-256 or MD5
• domain not configurable by default. Only configurable if APP_ADMINS_MANAGE_MULTI_DOMAINS is set to true in the global configuration. Otherwise APP_SIP_DOMAIN is used.
• activated optional, a boolean, set to false by default
• display_name optional, string
• email optional, must be an email, must be unique if ACCOUNT_EMAIL_UNIQUE is set to true
• admin optional, a boolean, set to false by default, create an admin account
• phone optional, a phone number, set a phone number to the account
• dtmf_protocol optional, values must be sipinfo, sipmessage or rfc2833
• dictionary optional, an associative array attached to the account, see also the related endpoints.
• Deprecated confirmation_key_expires optional, a datetime of this format: Y-m-d H:i:s. Only used when activated is not used or false. Enforces an expiration date on the returned confirmation_key. After that datetime public email or phone activation endpoints will return 403.

PUT /accounts/{id}¶

Admin

Update an existing account. Ensure to resend all the parameters to not reset them.

JSON parameters:

• username unique username, minimum 6 characters
• domain not configurable by default. Only configurable if APP_ADMINS_MANAGE_MULTI_DOMAINS is set to true in the global configuration. Otherwise APP_SIP_DOMAIN is used.
• password required minimum 6 characters
• algorithm required, values can be SHA-256 or MD5
• display_name optional, string
• email optional, must be an email, must be unique if ACCOUNT_EMAIL_UNIQUE is set to true
• admin optional, a boolean, set to false by default
• phone optional, a phone number, set a phone number to the account
• dtmf_protocol optional, values must be sipinfo, sipmessage or rfc2833

GET /accounts¶

Admin

Retrieve all the accounts, paginated.

GET /accounts/{id}¶

Admin

Retrieve a specific account.

GET /accounts/{sip}/search¶

Admin

Search for a specific account by sip address.

GET /accounts/{email}/search-by-email¶

Admin

Search for a specific account by email.

DELETE /accounts/{id}¶

Admin

Delete a specific account and its related information.

POST /accounts/{id}/activate¶

Admin

Activate an account.

POST /accounts/{id}/deactivate¶

Admin

Deactivate an account.

POST /accounts/{id}/block¶

Admin

Block an account.

POST /accounts/{id}/unblock¶

Admin

Unblock an account.

GET /accounts/{id}/provision¶

Admin

Provision an account by generating a fresh provisioning_token.

Accounts email¶

POST /accounts/me/email/request¶

User

Change the account email. An email will be sent to the new email address to confirm the operation.

JSON parameters:

• email the new email address, must be unique if ACCOUNT_EMAIL_UNIQUE is set to true

Accounts phone number¶

POST /accounts/me/phone/request¶

User

Request a specific code by SMS.

Will return 403 if the account doesn't have a validated Account Creation Token attached to it.

JSON parameters:

• phone the phone number to send the SMS

POST /accounts/me/phone¶

User

Confirm the code received and change the phone number. Activate the account.

JSON parameters:

• code the received SMS code

Return the updated account.

Accounts devices¶

GET /accounts/me/devices¶

User

Return the user registered devices.

DELETE /accounts/me/devices/{uuid}¶

User

Remove one of the user registered devices.

Account contacts¶

GET /accounts/me/contacts¶

User

Return the user contacts.

GET /accounts/me/contacts/{sip}¶

User

Return a user contact.

Contacts¶

GET /accounts/{id}/contacts¶

Admin

Get all the account contacts.

POST /accounts/{id}/contacts/{contact_id}¶

Admin

Add a contact to the list.

DELETE /accounts/{id}/contacts/{contact_id}¶

Admin

Remove a contact from the list.

Dictionary¶

GET /accounts/{id}/dictionary¶

Admin

Get all the account dictionary entries.

POST /accounts/{id}/dictionary/{key}¶

Admin

Add or update a new entry to the dictionary

JSON parameters:

• value required, the entry value

DELETE /accounts/{id}/dictionary/{key}¶

Admin

Remove an entry from the dictionary.

Account Actions¶

The following endpoints will return 403 Forbidden if the requested account doesn't have a DTMF protocol configured.

GET /accounts/{id}/actions¶

Admin

Show an account related actions.

GET /accounts/{id}/actions/{action_id}¶

Admin

Show an account related action.

POST /accounts/{id}/actions/¶

Admin

Create an account action.

JSON parameters:

• key required, alpha numeric with dashes, lowercase
• code required, alpha numeric, lowercase

PUT /accounts/{id}/actions/{action_id}¶

Admin

Create an account action.

JSON parameters:

• key required, alpha numeric with dashes, lowercase
• code required, alpha numeric, lowercase

DELETE /accounts/{id}/actions/{action_id}¶

Admin

Delete an account related action.

Contacts Lists¶

GET /contacts_lists¶

Admin

Show all the contacts lists.

GET /contacts_lists/{id}¶

Admin

Show a contacts list.

POST /contacts_lists¶

Admin

Create a contacts list.

JSON parameters:

• title required
• description required

PUT /contacts_lists/{id}¶

Admin

Update a contacts list.

JSON parameters:

• title required
• description required

DELETE /contacts_lists/{id}¶

Admin

Delete a contacts list.

POST /contacts_lists/{contacts_list_id}/contacts/{contact_id}¶

Admin

Add a contact to the contacts list.

DELETE /contacts_lists/{contacts_list_id}/contacts/{contact_id}¶

Admin

Remove a contact from the contacts list.

POST /accounts/{id}/contacts_lists/{contacts_list_id}¶

Admin

Add a contacts list to the account.

DELETE /accounts/{id}/contacts_lists/{contacts_list_id}¶

Admin

Remove a contacts list from the account.

Account Types¶

GET /account_types¶

Admin

Show all the account types.

GET /account_types/{id}¶

Admin

Show an account type.

POST /account_types¶

Admin

Create an account type.

JSON parameters:

• key required, alpha numeric with dashes, lowercase

PUT /account_types/{id}¶

Admin

Update an account type.

JSON parameters:

• key required, alpha numeric with dashes, lowercase

DELETE /account_types/{id}¶

Admin

Delete an account type.

POST /accounts/{id}/types/{type_id}¶

Admin

Add a type to the account.

DELETE /accounts/{id}/contacts/{type_id}¶

Admin

Remove a type from the account.

Messages¶

POST /messages¶

Admin

Send a message over SIP.

JSON parameters:

• to required, SIP address of the receiver
• body required, content of the message

Statistics¶

FlexiAPI can record logs generated by the FlexiSIP server and compile them into statistics.

POST /statistics/messages¶

Admin

Announce the creation of a message.

JSON parameters:

• id required, string
• from required, string the sender of the message
• sent_at required, string, format ISO8601, when the message was actually sent
• encrypted required, boolean
• conference_id string

PATCH /statistics/messages/{message_id}/to/{to}/devices/{device_id}¶

Admin

Complete a message status.

JSON parameters:

• last_status required, an integer containing the last status code
• received_at required, format ISO8601, when the message was received

POST /statistics/calls¶

Admin

Announce the beginning of a call.

JSON parameters:

• id required, string
• from required, string the initier of the call
• to required, string the destination of the call
• initiated_at required, string, format ISO8601, when the call was started
• ended_at string, format ISO8601, when the call finished
• conference_id string

PATCH /statistics/calls/{call_id}/devices/{device_id}¶

Admin

Complete a call status.

JSON parameters:

• rang_at format ISO8601, when the device rang
• invite_terminated
  • at format ISO8601, when the invitation ended
  • state the termination state

PATCH /statistics/calls/{call_id}¶

Admin

Update a call when ending.

JSON parameters:

• ended_at required, string, format ISO8601, when the call finished

Non-API Endpoints¶

The following URLs are not API endpoints they are not returning JSON content and they are not located under /api but directly under the root path.

Contacts list¶

GET /contacts/vcard¶

User

Return the authenticated user contacts list, in vCard 4.0 format.

Here is the format of the vCard list returned by the endpoint:

BEGIN:VCARD
VERSION:4.0
KIND:individual
IMPP:sip:schoen.tatyana@sip.linphone.org
FN:schoen.tatyana@sip.linphone.org
X-LINPHONE-ACCOUNT-DTMF-PROTOCOL:sipinfo
X-LINPHONE-ACCOUNT-TYPE:phone
X-LINPHONE-ACCOUNT-ACTION:action_key;123
END:VCARD
BEGIN:VCARD
VERSION:4.0
KIND:individual
IMPP:sip:dhand@sip.linphone.org
FN:dhand@sip.linphone.org
X-LINPHONE-ACCOUNT-DTMF-PROTOCOL:sipinfo
END:VCARD

GET /contacts/vcard/{sip}¶

User

Return a specific user authenticated contact, in vCard 4.0 format.