---
title: "Create a verification"
description: "Sends a one-time code by SMS to `destination`. Store the returned `id`; you need it to\n[check the code](#checkVerification) the user enters.\n"
version: "v2"
---

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

Path: MessagePort API › Verify

`POST /v3/verify`

Sends a one-time code by SMS to `destination`. Store the returned `id`; you need it to
[check the code](#checkVerification) the user enters.

## Authentication

- `basicAuth`, http, header `Authorization`

## Request body

_Required._

- `destination` (`createVerification.destination`; string, required) — Mobile number to verify. E.164 preferred; other formats are parsed.
- `source` (`createVerification.source`; string, optional) — Sender ID for the SMS. Must be a sender ID on your account. Defaults to your account's default sender.
- `template` (`createVerification.template`; string, optional) — Message text. Must contain `%code%`. Defaults to `Your verification code is %code%`.
  - maxLength 306
- `metadata` (`createVerification.metadata`; map<one of>, optional) — Up to 10 key/value pairs. Keys are strings of up to 50 characters; values are strings or integers of up to 100 characters.
  - example `{"order_id":1042,"customer":"C-889"}`
- `expiry_seconds` (`createVerification.expiry_seconds`; integer, optional) — How long the code can be used for.
  - min 10; max 3600; default `300`
- `token_length` (`createVerification.token_length`; integer, optional) — Length of the generated code.
  - min 6; max 10; default `6`

## Example request

```json
{
  "destination": "+61412345678",
  "template": "Your MessagePort code is %code%",
  "expiry_seconds": 300,
  "token_length": 6,
  "metadata": {
    "action": "login"
  }
}
```

## Code samples

### cURL

```bash
curl --request POST \
  --url https://app.messageport.com.au/api/v3/verify \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "destination": "+61412345678",
  "template": "Your MessagePort code is %code%",
  "expiry_seconds": 300,
  "token_length": 6,
  "metadata": {
    "action": "login"
  }
}
'
```

### TypeScript

```typescript
const url = 'https://app.messageport.com.au/api/v3/verify';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Basic <credentials>'},
  body: JSON.stringify({
    destination: '+61412345678',
    template: 'Your MessagePort code is %code%',
    expiry_seconds: 300,
    token_length: 6,
    metadata: {action: 'login'}
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://app.messageport.com.au/api/v3/verify"

payload = {
    "destination": "+61412345678",
    "template": "Your MessagePort code is %code%",
    "expiry_seconds": 300,
    "token_length": 6,
    "metadata": { "action": "login" }
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Basic <credentials>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

## Responses

### 201

Verification created and code sent.

#### Example

```json
{
  "data": {
    "id": "cb4d9527-1d3a-4def-85ba-f1fec9489c4f",
    "status": "sent",
    "type": "sms",
    "destination": "+61412345678",
    "source": "SHARED_NUMBER",
    "metadata": {
      "action": "login"
    },
    "template": "Your verification code is %code%",
    "expires_at": "2024-03-11T02:19:07.000000Z",
    "created_at": "2024-03-11T02:14:07.000000Z"
  }
}
```

- `data` (`createVerification.response.201.data`; object, optional)
  - example `{"id":"cb4d9527-1d3a-4def-85ba-f1fec9489c4f","status":"sent","type":"sms","destination":"+61412345678","source":"SHARED_NUMBER","metadata":{"action":"login"},"template":"Your verification code is %code%","expires_at":"2024-03-11T02:19:07.000000Z","created_at":"2024-03-11T02:14:07.000000Z"}`
  - `id` (`createVerification.response.201.data.id`; string, optional)
    - format `uuid`
  - `status` (`createVerification.response.201.data.status`; string, optional)
    - one of `"created"`, `"sent"`, `"expired"`, `"failed"`, `"verified"`, `"cancelled"`
  - `type` (`createVerification.response.201.data.type`; string, optional)
    - one of `"sms"`, `"email"`
  - `destination` (`createVerification.response.201.data.destination`; string, optional)
  - `source` (`createVerification.response.201.data.source`; string, optional)
  - `metadata` (`createVerification.response.201.data.metadata`; object | null, optional)
  - `template` (`createVerification.response.201.data.template`; string, optional)
  - `expires_at` (`createVerification.response.201.data.expires_at`; string, optional)
    - format `date-time`
  - `created_at` (`createVerification.response.201.data.created_at`; string, optional)
    - format `date-time`

### 401

Missing, malformed or invalid API credentials.

#### Example

```json
{
  "message": "Unauthenticated."
}
```

- `message` (`createVerification.response.401.message`; string, required)

### 422

The request failed validation. `errors` lists the messages for each invalid field.

#### Example

```json
{
  "message": "The messages field is required.",
  "errors": {
    "messages": [
      "The messages field is required."
    ]
  }
}
```

- `message` (`createVerification.response.422.message`; string, optional)
- `errors` (`createVerification.response.422.errors`; map<array<string>>, optional)


Source: https://dev.messageport.com.au/api/verify/create/index.md