# Overview ## Prerequisites To enable API in the FreeScout you need to install API & Webhooks module. All API requests should be made using UTF-8 encoding. ## Authentication API Key can be retrieved in "Manage » API & Webhoks". There are three ways to authenticate using API Key to make API calls: 1) Pass API Key in "api_key" GET-parameter: http://demo.freescout.net/api/conversations?api_key=c2ba609c687a3425402b9d881e5075db 2) Pass API Key as a username with a random password via HTTP Basic authentication: Authorization: c2ba609c687a3425402b9d881e5075db randompassword 3) Pass API Key as "X-FreeScout-API-Key" HTTP header: X-FreeScout-API-Key: c2ba609c687a3425402b9d881e5075db ## HTTP Methods {{----}} {{----}}

Method	Meaning
`GET`	Read one or more entities.
`POST`	Create new entity.
`PUT`	Update entity, overwriting all fields. When a field is not set in the request, it’s the same as if it was set with `null` value.
`PATCH`	Partially update entity using the JSON Patch format.
`DELETE`	Delete single entity.
`HEAD`	Same as `GET`, but the API returns an empty response.
`OPTIONS`	Returns allowed HTTP methods and `Access-Control-*` headers for `CORS` preflight request.

## Status Codes {{----}} {{----}}

Status Code	Name	Description
`200`	OK	Request was successful and response contains data.
`201`	Created	Resource was created. Response will contain either `Location` header or `Resource-ID` header. Usually for `POST` requests.
`204`	No Content	Request was successful and response is empty. Typical response for `PUT`, `PATCH` and `DELETE` requests.
`301`	Moved permanently	Requested entity existed under a different ID or path. Check the `Location` header.
`400`	Bad Request	Client error - the request doesn’t meet all requirements, see error messages.
`401`	Not Authorized	API Key is either not provided or not valid.
`403`	Access denied	Your API Key is valid, but you are denied access - the response should contain details.
`404`	Not Found	Resource was not found - it doesn’t exist or it was deleted.
`405`	Method Not Allowed	This error indicates that you are using incorrect HTTP method or incorrect API endpoint URL (allowed HTTP methods are URLs are described in this documentation for each API method) or you need to update API & Webhooks Module to the latest version (in older versions not all API methods were present).
`409`	Conflict	Resource cannot be created because conflicting entity already exists.
`412`	Precondition failed	The request was well formed and valid, but some other conditions were not met.
`413`	Request Entity Too Large	The payload of the request is larger than limit of the web server or PHP.
`415`	Unsupported Media Type	The API is unable to work with the provided payload.
`429`	Too Many Requests	You reached the rate limit
`500`	Internal Server Error	Whoops, looks like something went wrong on our end.
`503`	Service Unavailable	The API cannot process the request at the moment
`504`	Gateway Timeout	The API call timed-out. It is safe to retry the request after a short delay.

## Date Format All dates in the API are displayed and expected to be in ISO 8601 format in the UTC timezone:
YYYY-MM-DDThh:mm:ssZ ("Z" is the designator for the zero UTC offset). Example: 2020-01-02T23:00:00Z ## Errors Example of the error response is presented on the right side (or below).

	
{
    "message": "Bad request",
    "errorCode": "BAD REQUEST",
    "_embedded": {
        "errors": [
            {
                "path": "subject",
                "message": "may not be empty",
                "source": "JSON"
            },
            {
                "path": "status",
                "message": "Expected one of these: 'active', 'spam', 'open', 'closed', 'pending'",
                "rejectedValue": "Wrong",
                "source": "JSON"
            }
        ]
    }
}

	
{
    "message": "Bad request",
    "errorCode": "BAD REQUEST",
    "_embedded": {
        "errors": [
            {
                "path": "subject",
                "message": "may not be empty",
                "source": "JSON"
            },
            {
                "path": "status",
                "message": "Expected one of these: 'active', 'spam', 'open', 'closed', 'pending'",
                "rejectedValue": "Wrong",
                "source": "JSON"
            }
        ]
    }
}

	
{
    "message": "Bad request",
    "_embedded": {
        "errors": [
            {
                "path": "subject",
                "message": "may not be empty",
                "source": "JSON"
            },
            {
                "path": "status",
                "message": "Expected one of these: 'active', 'spam', 'open', 'closed', 'pending'",
                "rejectedValue": "Wrong",
                "source": "JSON"
            }
        ]
    }
}

{{--

Error Codes

EMPTY VALUE: Field cannot be empty.
VALUE NOT SUPPORTED: Provided value was not among predefined set of values.
SIZE: Value length must be in a predefined range. Please check documentation for the endpoint you were calling.
NOT WELL-FORMED EMAIL ADDRESS: Value is not a well formed email address.
NULL VALUE: Field cannot be null.
MALFORMED DATE: The value must be a valid ISO 8601 date with the format yyyy-MM-dd'T'HH:mm:ss'Z', for example 2017-03-31T23:30:01Z.
INVALID NUMBER: Value must be a number of predefined quality, for example must be greater than or equal to 5.
INVALID IDENTIFIER: Value is not a valid entity identifier. For example you may encounter this error if a negative number is used.
BAD REQUEST: Invalid input data.
ACCESS DENIED: You are not allowed to access the requested resource. There can be multiple reasons for this error - for example, you don’t have access to features like Reports.
CANNOT DELETE ATTACHMENT FROM PUBLISHED CONVERSATION: Attachments can only be deleted from drafts, not published conversations.
INVALID URI: The endpoint URI is not well formed. While the API always tries to explain the specific error and pinpoint wrong query parameters it is not always possible. Please check documentation for the endpoint you were calling.
INVALID JSON: The request body either isn’t well formed JSON or JSON structure doesn’t conform to the endpoint’s specification - number is used instead of object or the other way around.
CONFLICT: Entity cannot be created because conflicting entity already exists. Typical example is when you try to add a customer email that is already being used by another customer.
INVALID NUMBER: The provided value is not a non-negative integer (i.e. five instead of 5321).
UNSUPPORTED MEDIA TYPE: API expected JSON Content-Type header but received something else.
UNSUPPORTED HTTP METHOD: The given endpoint does not support the HTTP method used, see the error message for list of supported HTTP methods and/or consult the documentation for the particular endpoint.
ALLOWED PATCH OPERATIONS: You either used invalid JSONPatch operation or the operation you used is not permitted for the update path. For example you can only remove field that is nullable.

--}} {{-- CONVERSATION LOCKED - TOO MANY THREADS The maximum number of threads in a single conversation was reached. If you want to add a new thread, create a new conversation. If you wanted to create a conversation, please ensure the number of threads is below 100. CONVERSATION LOCKED - CONVERSATION IS TOO OLD Company policy prevents updating old conversations. If you want to add a new thread, create a new conversation. VALID CONVERSATION OWNER The user ID is not a valid conversation owner - it has to be ID of a user from your account. VALID IMPORTED THREAD When creating imported threads it is possible to set a createdAt value, but only if imported field is set to true. ENUM VALUE The provided value has to be from a predefined list of values, the error message provides list of the allowed values. LIST OF ENUM VALUES The provided list of values has to be from a predefined list of values, separated by comma. The error message provides a list of the allowed values. REJECTED REQUEST The request was rejected because the URI did not conform to the rules. Please consult the documentation for the particular endpoint. --}}