> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superoffice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents WebAPI

> The Agents API contains everything in the normal web service API but does not attempt to model entities.

The Agents API contains everything in the normal web service API but does not attempt to model entities. It exposes the latest Services agents and functions. All operations are accessed using HTTP POST.

To get the version and more info, [access the API endpoint][7]: ./`/api`

<Note>
  The agents do not return HTTP errors - a failed call will return NULL instead.
</Note>

**Examples:**

```http theme={null}
POST /api/v1/Agents/Contact/GetContact?contactId=123
```

Returns a JSON object representing Contact 123.

```http theme={null}
POST /api/v1/Agents/List/SaveListItemEntity
```

Adds a new list item to the Category list (assuming the list item entity parameter has been properly initialized).

## GET vs. POST

`GET /api/v1/Agents/Appointment/CalculateDays`

GET this to get a description of the call. The method is not invoked using GET, even if the method is called **GetAppointment**. To actually invoke the method, you need to POST to the endpoint:

```http theme={null}
POST /api/v1/Agents/Appointment/CalculateDays
{ "Contact": { "ContactId": 123 },
  "AppointmentId": 1234,
  "Description": "string",
  "StartDate": "2021-06-06T13:02:55Z",
  "EndDate": "2021-06-06T13:02:55Z"
}
```

This method takes an appointment entity as its parameter so this needs to be in the POST body. The result of the service call is returned as JSON or XML, depending on the Accept header.

## Errors

Errors are returned as a NULLs. You may also get a 200 OK with an internal error object.

<Note>
  Check the response object, not just the HTTP status code.
</Note>

**HTTP 400 Bad Request - with an error result:**

```http theme={null}
POST api/v1/Agents/Contact/GetContactEntity?contactEntityId=glops
```

Happens when the request is malformed.

**HTTP 200 OK - with a NULL result:**

```http theme={null}
POST api/v1/Agents/Contact/GetContactEntity?contactEntityId=9999
```

Happens when the request succeeds but there is nothing to return.

**200 OK with an internal error object:**

```javascript theme={null}
{
  "Message": "The request is invalid.",
  "MessageDetail": "The parameters dictionary contains a null entry for parameter 'contactEntityId'."
}
```

Happens when the request succeeds but the data is invalid. For example, a required parameter is missing.

## How to

<Note>
  The examples below are given using JavaScripty pseudocode.
</Note>

* [Create a new company][2]
* [Add a category list item][3]
* [Add a document template][4]
* [Generate a document][5]

***

## You might also be interested in

* [Learn the REST WebAPI][1]
* [Look up endpoints in the Agents reference][8]
* [Download REST WebAPI Swagger file][6]

[1]: ../rest-webapi/index

[2]: ../../howto/company/create-contact

[3]: ../../howto/company/add-catlist-item-webapi-agents

[4]: ../../howto/document/rest-add-document-template

[5]: ../../howto/document/rest-generate-document

[6]: ../../../../../downloads/api/Swagger-v1-Agents.zip

[7]: ../get-webapi-version

[8]: ../../../reference/restful/agent/index


## Related topics

- [Agents WebAPI](/en/api/web-services/endpoints/agents-webapi/index.md)
- [SuperOffice.WebApi.Agents.MDOAgent](/en/api/reference/webapi/SuperOffice.WebApi.Agents.MDOAgent.md)
- [SuperOffice.WebApi.Agents.BLOBAgent](/en/api/reference/webapi/SuperOffice.WebApi.Agents.BLOBAgent.md)
- [SuperOffice.WebApi.Agents.AIAgent](/en/api/reference/webapi/SuperOffice.WebApi.Agents.AIAgent.md)
- [SuperOffice.WebApi.Agents.IMDOAgent](/en/api/reference/webapi/SuperOffice.WebApi.Agents.IMDOAgent.md)
- [SuperOffice.WebApi.Agents.IBLOBAgent](/en/api/reference/webapi/SuperOffice.WebApi.Agents.IBLOBAgent.md)
- [SuperOffice.WebApi.Agents.IAIAgent](/en/api/reference/webapi/SuperOffice.WebApi.Agents.IAIAgent.md)