# REST API — Introduction


Source: https://vertexsms.com/en/api/introduction

**Building an AI integration?** See the [MCP server documentation](https://vertexsms.com/en/mcp/introduction) — it lets Claude, Cursor, VS Code, and other AI assistants use VertexSMS without any glue code.

The VertexSMS API is based on REST principles. To use it you need a VertexSMS account and an API access token. You can generate them inside your VertexSMS account. You must supply a `Content-type: application/json` header on all PUT or POST requests.

## HTTP headers and codes

The REST API uses standard HTTP status codes:

| Code | Description |
|------|-------------|
| 200 | Success. |
| 400 | General error when fulfilling the request would cause an invalid state. Domain validation errors, missing data, etc. |
| 401 | Similar to 403, but specifically when authentication is possible but has failed or has not yet been provided. |
| 403 | Server understood the request but refuses to fulfil it. Authorisation will not help and the request SHOULD NOT be repeated. |
| 404 | Server has not found anything matching the Request-URI. No indication is given whether the condition is temporary or permanent. |
| 405 | Method specified in the Request-Line is not allowed for the resource identified by the Request-URI. |
| 409 | Request could not be completed due to a conflict with the current state of the resource. |
| 500 | Server error, please try again. |
| 501 | Server error, please try again. |
| 503 | Server is currently unable to handle the request due to temporary overloading or maintenance. Please try again. |

## Handling errors

If the API rejects your request, an error is returned as a 4xx (or 500 if our systems fail) HTTP status code with a JSON-encoded body describing the error.

Bad request example:

```
POST /sms HTTP/1.1
Host: api.vertexsms.com
Content-Type: application/json
Accept: application/json
X-VertexSMS-Token: eB52vNTPL9fO3rDrx8pYmVnj6nqceHNhnqceHNh

{ "to": "37069912345", "from": "invalid sender ID", "message": "Test SMS 001" }
```

Response:

```
HTTP/1.1 400 Bad Request
Content-Type: application/json

{ "message": "Invalid value for field 'from'. Sender ID must either be a valid MSISDN or an alpha-numeric string (max. length: 11 characters), which may consist only of upper+lower-case latin letters, digits, spaces and dots." }
```

## Security

Use HTTPS for all VertexSMS API requests. All callbacks from VertexSMS are made only from the IP ranges `178.33.133.192/28` and `178.32.167.92`.