flexisip-account-manager/flexiapi/resources/views/api/documentation_markdown.blade.php

# 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
```

<div class="card">

Restricted endpoints are protected using a DIGEST authentication or an API Key mechanisms.

### Access model

The endpoints are accessible using three different models:

- <span class="badge badge-success">Public</span> publicly accessible
- <span class="badge badge-info">User</span> the endpoint can only be accessed by an authenticated user
- <span class="badge badge-warning">Admin</span> the endpoint can be only be accessed by an authenticated admin user
- <span class="badge badge-error">Super Admin</span> the endpoint can be only be accessed by an authenticated super admin user

### Space expiration

<span class="badge badge-error">Super Admin</span> can configure and expiration date on Spaces (`expire_at`). If the Space is expired all the authenticated endpoint of the API will return `403`.

### Localization

You can add an [`Accept-Language`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language) header to your request to translate the responses, and especially errors messages, in a specific language.

Currently supported languages: @php
    echo implode(', ', config('app.authorized_locales'))
@endphp

```
> GET /api/{endpoint}
> Accept-Language: fr
> …

< HTTP 422
< {
<   "message": "Le champ pseudo est obligatoire.",
<   "errors": {
<     "username": [
<       0 => "Le champ pseudo est obligatoire."
<     ]
<   }
< }

```

### Using the API Key

You can retrieve an API Key from your account panel or using <a href="#get-accountsmeapikey">the dedicated API endpoint</a>.

**When generated by a User account the generated API Key will be restricted to the IP that generates it and will be destroyed if not used after some times.**

**If you want a stable API Key, to integrate with another server component for example, you can generate one in the Administration Panel.**

You can then use your freshly generated key by adding a new `x-api-key` header to your API requests:

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

Or using a cookie:

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

### Using a JWT token

You can use a <a href="https://jwt.io/">JWT</a> token to authenticate on the API.

To do so you MUST inject it as an `Authorization: Bearer` header and configure the API with the public key of the token emitter.

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

The API will then check if the token was signed properly, is still valid and authenticate a user that is actually available in the system.

### Using DIGEST

To discover the available hashing algorythm you MUST send an unauthenticated request to one of the restricted endpoints.<br />
Only DIGEST-MD5 and DIGEST-SHA-256 are supported through the authentication layer.

A `from` (consisting of the user SIP address, prefixed with `sip:`) header is required to initiate the DIGEST flow.

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

You can find more documentation on the related [IETF RFC-7616](https://tools.ietf.org/html/rfc7616).

</div>

# Endpoints

## Ping

### `GET /ping`
<span class="badge badge-success">Public</span>

Returns `pong`

## Spaces

Manage the list of allowed `spaces`. The admin accounts declared with a `domain` that is a `super` `sip_domain` will become <span class="badge badge-error">Super Admin</span>.

### `GET /spaces`
<span class="badge badge-error">Super Admin</span>

Get the list of declared Spaces.

### `GET /spaces/{domain}`
<span class="badge badge-error">Super Admin</span>

Get a Space.

### `POST /spaces`
<span class="badge badge-error">Super Admin</span>

Create a new `sip_domain`.

JSON parameters:

* `name` **required**, the space name
* `domain` **required**, the SIP domain to use, must be unique
* `super` **required**, boolean, set the domain as a Super Domain
* `disable_chat_feature` boolean, disable the chat feature, default to `false`
* `disable_meetings_feature` boolean, disable the meeting feature, default to `false`
* `disable_broadcast_feature` boolean, disable the broadcast feature, default to `true`
* `hide_settings` boolean, hide the app settings, default to `false`
* `hide_account_settings` boolean, disable the account settings, default to `false`
* `disable_call_recordings_feature` boolean, disable the call recording feature, default to `false`
* `only_display_sip_uri_username` boolean, hide the SIP uris in the app, default to `false`
* `assistant_hide_create_account` boolean, disable the account creation assistant, default to `false`
* `assistant_disable_qr_code` boolean, disable the QR code feature in the assistant, default to `false`
* `assistant_hide_third_party_account` boolean, disable the call recording feature, default to `false`
* `max_account` integer, the maximum number of accounts configurable in the app, default to `0` (infinite)
* `max_accounts` integer, the maximum number of accounts that can be created in the space, default to `0` (infinite), cannot be less than the actual amount of accounts
* `expire_at` date, the moment the space is expiring, default to `null` (never expire)
* `copyright_text` text, the copyright text
* `intro_registration_text` Markdown text, the main registration page text
* `newsletter_registration_address`, the newsletter registration email address
* `account_proxy_registrar_address`, the account proxy registrar address
* `account_realm`, the default realm for the accounts, fallback to the domain if not set
* `custom_provisioning_entries` text, the custom configuration used for the provisioning
* `custom_provisioning_overwrite_all` boolean, allow the custom configuration to overwrite the default one
* `provisioning_use_linphone_provisioning_header` boolean
* `custom_theme` boolean, allow a custom CSS file to be loaded
* `web_panel` boolean, the web panel switch
* `public_registration` boolean, the public registration switch
* `phone_registration` boolean, the phone registration switch
* `intercom_features` boolean, the intercom features switch

### `PUT /spaces/{domain}`
<span class="badge badge-error">Super Admin</span>

Update an existing `sip_domain`.

JSON parameters:

* `name` **required**, the space name
* `super` **required**, boolean, set the domain as a Super Domain
* `disable_chat_feature` **required**, boolean
* `disable_meetings_feature` **required**, boolean
* `disable_broadcast_feature` **required**, boolean
* `hide_settings` **required**, boolean
* `hide_account_settings` **required**, boolean
* `disable_call_recordings_feature` **required**, boolean
* `only_display_sip_uri_username` **required**, boolean
* `assistant_hide_create_account` **required**, boolean
* `assistant_disable_qr_code` **required**, boolean
* `assistant_hide_third_party_account` **required**, boolean
* `max_account` **required**, integer
* `max_accounts` **required**,integer, the maximum number of accounts that can be created in the space, default to `0` (infinite), cannot be less than the actual amount of accounts
* `expire_at` **required**, date, the moment the space is expiring, set to `null` to never expire
* `copyright_text` **required**, text, the copyright text
* `intro_registration_text` **required**, Markdown text, the main registration page text
* `newsletter_registration_address`, **required**, the newsletter registration email address
* `account_proxy_registrar_address`, **required**, the account proxy registrar address
* `account_realm`, **required**, the default realm for the accounts, fallback to the domain if not set
* `custom_provisioning_entries` **required**, text, the custom configuration used for the provisioning
* `custom_provisioning_overwrite_all` **required**, boolean, allow the custom configuration to overwrite the default one
* `provisioning_use_linphone_provisioning_header` **required**, boolean
* `custom_theme` **required**, boolean, allow a custom CSS file to be loaded
* `web_panel` **required**, boolean, the web panel switch
* `public_registration` **required**, boolean, the public registration switch
* `phone_registration` **required**, boolean, the phone registration switch
* `intercom_features` **required**, boolean, the intercom features switch

### `DELETE /spaces/{domain}`
<span class="badge badge-error">Super Admin</span>

Delete a domain, **be careful, all the related accounts will also be destroyed**.

### `GET /spaces/{domain}/email`
<span class="badge badge-error">Super Admin</span>

Get a space email server configuration

### `POST /spaces/{domain}/email`
<span class="badge badge-error">Super Admin</span>

Update an existing a space email server configuration.

JSON parameters:

* `host` **required**, the email server hostname
* `port` **required**, integer, the port
* `username`, the username
* `password`, the password
* `from_address`, email address, the sender email address
* `from_name`, the sender name
* `signature`, a text that will end every emails sent

### `DELETE /spaces/{domain}/email`
<span class="badge badge-error">Super Admin</span>

Delete the a space email server configuration.

## 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`
<span class="badge badge-success">Public</span>

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`
<span class="badge badge-success">Public</span>

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` **required**, the push notification provider, must be in apns.dev, apns or fcm
* `pn_param` the push notification parameter, can be null or contain only alphanumeric and underscore characters
* `pn_prid` the push notification unique id, can be null or contain only alphanumeric, dashes, underscore and colon characters

### `POST /account_creation_tokens/using-account-creation-request-token`
<span class="badge badge-success">Public</span>

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/consume`
<span class="badge badge-info">User</span>

Consume an `account_creation_token` and link it to the authenticated account.
Return an `account_creation_token`.

Return `404` if the `account_creation_token` provided is not valid.

JSON parameters:

* `account_creation_token` **required**

### `POST /account_creation_tokens`
<span class="badge badge-warning">Admin</span>

Create and return an `account_creation_token`.

## Account Recovery Tokens

An `account_recovery_token` is a unique token that allow the recovery of an account.

It can be used on the following page that also accepts a `phone` optional parameter to prefil the recovery form:

    {{ route('account.recovery.show.phone', ['account_recovery_token' => '_the_token_']) }}
    {{ route('account.recovery.show.phone', ['account_recovery_token' => '_the_token_', 'phone' => '+3312341234']) }}

### `POST /account_recovery_tokens/send-by-push`
<span class="badge badge-success">Public</span>

Create and send an `account_recovery_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` **required**, the push notification provider, must be in apns.dev, apns or fcm
* `pn_param` the push notification parameter, can be null or contain only alphanumeric and underscore characters
* `pn_prid` the push notification unique id, can be null or contain only alphanumeric, dashes, underscore and colon characters

## Auth Tokens

### `POST /accounts/auth_token`
<span class="badge badge-success">Public</span>

Generate an `auth_token`. To attach the generated token to an account see [`auth_token` attachement endpoint](#get-accountsauthtokenauthtokenattach).

Return the `auth_token` object.

### `GET /accounts/auth_token/{auth_token}/attach`
<span class="badge badge-info">User</span>

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

Return `404` if the token is non existing or invalid.

## Accounts

### `POST /accounts/with-account-creation-token`
<span class="badge badge-success">Public</span>

Create an account using an `account_creation_token`.

Return `422` if the parameters are invalid or if the token is expired.

Return `403` if the `max_accounts` limit of the corresponding Space is reached.

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`
<span class="badge badge-success">Public</span>

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

### `GET /accounts/me/api_key/{auth_token}`
<span class="badge badge-success">Public</span>

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](#get-accountsauthtokenauthtokenattach) 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`
<span class="badge badge-info">User</span>

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

### `GET /accounts/me`
<span class="badge badge-info">User</span>

Retrieve the account information.

### `GET /accounts/me/services/turn`
<span class="badge badge-info">User</span>

If configured, returns valid TURN credentials following the [draft-uberti-behave-turn-rest-00 IEFT Draft](https://datatracker.ietf.org/doc/html/draft-uberti-behave-turn-rest-00).

### `GET /accounts/me/provision`
<span class="badge badge-info">User</span>

Provision the account by generating a fresh `provisioning_token`.

Return the account object.

### `DELETE /accounts/me`
<span class="badge badge-info">User</span>

Delete the account.

### `POST /accounts/me/password`
<span class="badge badge-info">User</span>

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`
<span class="badge badge-warning">Admin</span>

To create an account directly from the API.

Return `403` if the `max_accounts` limit of the corresponding Space is reached.

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**, must exist in one of the configured Spaces. Only configurable if the admin is a super admin. Otherwise the SIP domain of the corresponding space 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 valid 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, <a href="#dictionary">see also the related endpoints</a>.

### `PUT /accounts/{id}`
<span class="badge badge-warning">Admin</span>

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**, must exist in one of the configured Spaces. Only configurable if the admin is a super admin. Otherwise the SIP domain of the corresponding space 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 valid phone number, set a phone number to the account
* `dtmf_protocol` optional, values must be `sipinfo`, `sipmessage` or `rfc2833`

Using this endpoint you can also set a fresh dictionnary if the parameter is set. The existing dictionary entries will be destroyed.

* `dictionary` optional, an associative array attached to the account, <a href="#dictionary">see also the related endpoints</a>.

This endpoint also return the current `phone_change_code` and `email_change_code` if they are available.

### `GET /accounts`
<span class="badge badge-warning">Admin</span>

Retrieve all the accounts, paginated.

### `GET /accounts/{id}`
<span class="badge badge-warning">Admin</span>

Retrieve a specific account.

### `GET /accounts/{sip}/search`
<span class="badge badge-warning">Admin</span>

Search for a specific account by sip address.

### `GET /accounts/{email}/search-by-email`
<span class="badge badge-warning">Admin</span>

Search for a specific account by email.

### `DELETE /accounts/{id}`
<span class="badge badge-warning">Admin</span>

Delete a specific account and its related information.

### `POST /accounts/{id}/activate`
<span class="badge badge-warning">Admin</span>

Activate an account.

### `POST /accounts/{id}/deactivate`
<span class="badge badge-warning">Admin</span>

Deactivate an account.

### `POST /accounts/{id}/block`
<span class="badge badge-warning">Admin</span>

Block an account.

### `POST /accounts/{id}/unblock`
<span class="badge badge-warning">Admin</span>

Unblock an account.

### `GET /accounts/{id}/provision`
<span class="badge badge-warning">Admin</span>

Provision an account by generating a fresh `provisioning_token`.

### `POST /accounts/{id}/send_provisioning_email`
<span class="badge badge-warning">Admin</span>

Send a provisioning email to the account.

### `POST /accounts/{id}/send_reset_password_email`
<span class="badge badge-warning">Admin</span>

Send a password reset email to the account.

## Accounts email

### `POST /accounts/me/email/request`
<span class="badge badge-info">User</span>

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

Will return `403` if the account doesn't have a validated <a href='#account-creation-tokens'>Account Creation Token</a> attached to it.

JSON parameters:

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

### `POST /accounts/me/email`
<span class="badge badge-info">User</span>

Confirm the code received and change the email.
Activate the account.

JSON parameters:

* `code` the code received by email

Return the updated account.

## Accounts phone number

### `POST /accounts/me/phone/request`
<span class="badge badge-info">User</span>

Request a specific code by SMS to change the phone number.

Will return `403` if the account doesn't have a validated <a href='#account-creation-tokens'>Account Creation Token</a> attached to it.

JSON parameters:

* `phone` the phone number to send the SMS

### `POST /accounts/me/phone`
<span class="badge badge-info">User</span>

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/{id/me}/devices`
<span class="badge badge-warning">Admin</span>
<span class="badge badge-info">User</span>

Return the user registered devices.

### `DELETE /accounts/{id/me}/devices/{uuid}`
<span class="badge badge-warning">Admin</span>
<span class="badge badge-info">User</span>

Remove one of the user registered devices.

## Account contacts

### `GET /accounts/me/contacts`
<span class="badge badge-info">User</span>

Return the user contacts.

### `GET /accounts/me/contacts/{sip}`
<span class="badge badge-info">User</span>

Return a user contact.

## vCards storage

### `POST /accounts/{id/me}/vcards-storage`
<span class="badge badge-warning">Admin</span>
<span class="badge badge-info">User</span>

Store a vCard.

JSON parameters:

* `vcard`, mandatory, a valid vCard having a mandatory `UID` parameter that is uniquelly identifying it. This `UID` parameter will then be used to manipulate the vcard through the following endpoints as `uuid`.

### `PUT /accounts/{id/me}/vcards-storage/{uuid}`
<span class="badge badge-warning">Admin</span>
<span class="badge badge-info">User</span>

Update a vCard.

JSON parameters:

* `vcard`, mandatory, a valid vCard having a mandatory `UID` parameter that is uniquelly identifying it and is the same as the `uuid` parameter.

### `GET /accounts/{id/me}/vcards-storage`
<span class="badge badge-warning">Admin</span>
<span class="badge badge-info">User</span>

Return the list of stored vCards

### `GET /accounts/{id/me}/vcards-storage/{uuid}`
<span class="badge badge-warning">Admin</span>
<span class="badge badge-info">User</span>

Return a stored vCard

### `DELETE /accounts/{id/me}/vcards-storage/{uuid}`
<span class="badge badge-warning">Admin</span>
<span class="badge badge-info">User</span>

Delete a stored vCard

## Contacts

### `GET /accounts/{id}/contacts`
<span class="badge badge-warning">Admin</span>

Get all the account contacts.

### `POST /accounts/{id}/contacts/{contact_id}`
<span class="badge badge-warning">Admin</span>

Add a contact to the list.

### `DELETE /accounts/{id}/contacts/{contact_id}`
<span class="badge badge-warning">Admin</span>

Remove a contact from the list.

## Dictionary

### `GET /accounts/{id}/dictionary`
<span class="badge badge-warning">Admin</span>

Get all the account dictionary entries.

### `POST /accounts/{id}/dictionary/{key}`
<span class="badge badge-warning">Admin</span>

Add or update a new entry to the dictionary

JSON parameters:

* `value` **required**, the entry value

## External Account

### `GET /accounts/{id}/external`
<span class="badge badge-warning">Admin</span>

Get the external account.

### `POST /accounts/{id}/external`
<span class="badge badge-warning">Admin</span>

Create or update the external account.

JSON parameters:

* `username` **required**
* `domain` **required**
* `password` **required**
* `realm` must be different than `domain`
* `registrar` must be different than `domain`
* `outbound_proxy` must be different than `domain`
* `protocol` **required**, must be `UDP`, `TCP` or `TLS`

### `DELETE /accounts/{id}/external`
<span class="badge badge-warning">Admin</span>

Delete the external account.

## Account Actions

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

### `GET /accounts/{id}/actions`
<span class="badge badge-warning">Admin</span>

Show an account related actions.

### `GET /accounts/{id}/actions/{action_id}`
<span class="badge badge-warning">Admin</span>

Show an account related action.

### `POST /accounts/{id}/actions/`
<span class="badge badge-warning">Admin</span>

Create an account action.

JSON parameters:

* `key` **required**, alpha numeric with dashes, lowercase
* `code` **required**, alpha numeric, lowercase

### `PUT /accounts/{id}/actions/{action_id}`
<span class="badge badge-warning">Admin</span>

Create an account action.

JSON parameters:

* `key` **required**, alpha numeric with dashes, lowercase
* `code` **required**, alpha numeric, lowercase

### `DELETE /accounts/{id}/actions/{action_id}`
<span class="badge badge-warning">Admin</span>

Delete an account related action.

## Contacts Lists

### `GET /contacts_lists`
<span class="badge badge-warning">Admin</span>

Show all the contacts lists.

### `GET /contacts_lists/{id}`
<span class="badge badge-warning">Admin</span>

Show a contacts list.

### `POST /contacts_lists`
<span class="badge badge-warning">Admin</span>

Create a contacts list.

JSON parameters:

* `title` **required**
* `description` **required**

### `PUT /contacts_lists/{id}`
<span class="badge badge-warning">Admin</span>

Update a contacts list.

JSON parameters:

* `title` **required**
* `description` **required**

### `DELETE /contacts_lists/{id}`
<span class="badge badge-warning">Admin</span>

Delete a contacts list.

### `POST /contacts_lists/{contacts_list_id}/contacts/{contact_id}`
<span class="badge badge-warning">Admin</span>

Add a contact to the contacts list.

### `DELETE /contacts_lists/{contacts_list_id}/contacts/{contact_id}`
<span class="badge badge-warning">Admin</span>

Remove a contact from the contacts list.

### `POST /accounts/{id}/contacts_lists/{contacts_list_id}`
<span class="badge badge-warning">Admin</span>

Add a contacts list to the account.

### `DELETE /accounts/{id}/contacts_lists/{contacts_list_id}`
<span class="badge badge-warning">Admin</span>

Remove a contacts list from the account.

## Account Types

### `GET /account_types`
<span class="badge badge-warning">Admin</span>

Show all the account types.

### `GET /account_types/{id}`
<span class="badge badge-warning">Admin</span>

Show an account type.

### `POST /account_types`
<span class="badge badge-warning">Admin</span>

Create an account type.

JSON parameters:

* `key` **required**, alpha numeric with dashes, lowercase

### `PUT /account_types/{id}`
<span class="badge badge-warning">Admin</span>

Update an account type.

JSON parameters:

* `key` **required**, alpha numeric with dashes, lowercase

### `DELETE /account_types/{id}`
<span class="badge badge-warning">Admin</span>

Delete an account type.

### `POST /accounts/{id}/types/{type_id}`
<span class="badge badge-warning">Admin</span>

Add a type to the account.

### `DELETE /accounts/{id}/contacts/{type_id}`
<span class="badge badge-warning">Admin</span>

Remove a type from the account.

## Messages

### `POST /messages`
<span class="badge badge-warning">Admin</span>

Send a message over SIP.

JSON parameters:

* `to` **required**, SIP address of the receiver
* `body` **required**, content of the message

## Push Notifications

### `POST /push_notification`
<span class="badge badge-info">User</span>

Send a push notification using the Flexisip Pusher.

JSON parameters:

* `pn_provider` **required**, the push notification provider, must be in `apns.dev`, `apns` or `fcm`
* `pn_param` the push notification parameter, can be null or contain only alphanumeric and underscore characters
* `pn_prid` the push notification unique id, can be null or contain only alphanumeric, dashes, underscore and colon characters
* `type` **required**, must be in `background`, `message` or `call`
* `call_id` a Call ID, must have only alphanumeric, tilde and dashes characters

## Phone Countries

The phone numbers managed by FlexiAPI are validated against a list of countries that can be managed in the admin web panels.

### `GET /phones_countries`
<span class="badge badge-success">Public</span>

Return the list of Phone Countries and their current status.

If a country is deactivated all the new submitted phones submitted on the platform will be blocked.

## Statistics

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

### `POST /statistics/messages`
<span class="badge badge-warning">Admin</span>

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}`
<span class="badge badge-warning">Admin</span>

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`
<span class="badge badge-warning">Admin</span>

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}`
<span class="badge badge-warning">Admin</span>

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}`
<span class="badge badge-warning">Admin</span>

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`
<span class="badge badge-info">User</span>

Return the authenticated user contacts list, in [vCard 4.0 format](https://datatracker.ietf.org/doc/html/rfc6350).

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}`
<span class="badge badge-info">User</span>

Return a specific user authenticated contact, in [vCard 4.0 format](https://datatracker.ietf.org/doc/html/rfc6350).

## vCards Storage

<!---
The following headers are mandatory to access the following endpoints:
```
> content-type: text/vcard
> accept: text/vcard
```
--->

### `GET /vcards-storage`

<span class="badge badge-info">User</span>

Return the list of stored vCards

### `GET /vcards-storage/{uuid}`
<span class="badge badge-info">User</span>

Return a stored vCard