# Understand a date and time and return it as ISO 8601 and epoch

`POST /v1/convert/string/date/to/iso_8601`

Reads an epoch number (seconds or milliseconds, detected and reported), ISO 8601 text, or a common text format such as 16/10/2026 14:30 or Oct 16, 2026 2:30 PM. Add a format hint to use your own pattern. Text without an offset is read in the time zone you give, and the result is shown in it. Returns ISO text, epoch seconds and epoch milliseconds.

## Request body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| value | string | yes | The date and time as text, or an epoch number |
| format | string | no | A format hint such as %d/%m/%Y %H:%M. When given, only this format is tried |
| tz | string | no | Time zone (IANA name such as Europe/Lisbon). Text without an offset is read in it, and the result is shown in it (default `"UTC"`) |
| day_first | boolean | no | For slashed dates such as 03/04/2026: read the first number as the day (default `false`) |

## Example request

A request body that works, as JSON.

```json
{
  "value": "13/10/2023 12:00",
  "tz": "Europe/Lisbon",
  "day_first": true
}
```

## Code samples

Replace YOUR_TOKEN with your access token.

### curl

```shell
curl -X POST 'https://api.skillfulsardine.com/v1/convert/string/date/to/iso_8601' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "value": "13/10/2023 12:00",
  "tz": "Europe/Lisbon",
  "day_first": true
}'
```

### PowerShell

```powershell
$body = @'
{
  "value": "13/10/2023 12:00",
  "tz": "Europe/Lisbon",
  "day_first": true
}
'@
$response = Invoke-RestMethod -Method Post -Uri 'https://api.skillfulsardine.com/v1/convert/string/date/to/iso_8601' `
  -Headers @{ Authorization = 'Bearer YOUR_TOKEN' } `
  -ContentType 'application/json; charset=utf-8' `
  -Body ([System.Text.Encoding]::UTF8.GetBytes($body))
$response | ConvertTo-Json -Depth 10
```

### Python

```python
import requests

payload = {
    "value": "13/10/2023 12:00",
    "tz": "Europe/Lisbon",
    "day_first": True,
}

response = requests.post(
    "https://api.skillfulsardine.com/v1/convert/string/date/to/iso_8601",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json=payload,
    timeout=30,
)
print(response.json())
```

### JavaScript

```javascript
const response = await fetch("https://api.skillfulsardine.com/v1/convert/string/date/to/iso_8601", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "value": "13/10/2023 12:00",
  "tz": "Europe/Lisbon",
  "day_first": true
}),
});
const result = await response.json();
console.log(result);
```

### Node

```javascript
// Node 18 or later. Save as call.mjs and run: API_TOKEN=... node call.mjs
const token = process.env.API_TOKEN;

const response = await fetch("https://api.skillfulsardine.com/v1/convert/string/date/to/iso_8601", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "value": "13/10/2023 12:00",
  "tz": "Europe/Lisbon",
  "day_first": true
}),
});
const result = await response.json();
console.log(result);
```

### Rust

```rust
// Cargo.toml: reqwest = { version = "0.12", features = ["blocking", "json"] }, serde_json = "1"
fn main() -> Result<(), Box<dyn std::error::Error>> {
    let body: serde_json::Value = serde_json::from_str(r#"{
  "value": "13/10/2023 12:00",
  "tz": "Europe/Lisbon",
  "day_first": true
}"#)?;
    let response = reqwest::blocking::Client::new()
        .post("https://api.skillfulsardine.com/v1/convert/string/date/to/iso_8601")
        .bearer_auth("YOUR_TOKEN")
        .json(&body)
        .send()?;
    println!("{}", response.text()?);
    Ok(())
}
```

### Swift

```swift
import Foundation

var request = URLRequest(url: URL(string: "https://api.skillfulsardine.com/v1/convert/string/date/to/iso_8601")!)
request.httpMethod = "POST"
request.setValue("Bearer YOUR_TOKEN", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = Data(#"""
{
  "value": "13/10/2023 12:00",
  "tz": "Europe/Lisbon",
  "day_first": true
}
"""#.utf8)

let (data, _) = try await URLSession.shared.data(for: request)
print(String(decoding: data, as: UTF8.self))
```

## Response

The fields inside `data` of a successful response.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| iso | string | yes | ISO 8601 text with the offset of tz |
| epoch_seconds | integer | yes | Whole seconds since 1970-01-01 UTC |
| epoch_milliseconds | integer | yes | Milliseconds since 1970-01-01 UTC |
| detected | one of: epoch_seconds, epoch_milliseconds, iso, text | yes | epoch_seconds, epoch_milliseconds, iso or text |
| matched_format | string | no | For text: the format that matched |
| timezone | string | yes | The time zone of iso |

## Example response

A real answer from the operation, as JSON. The fields in the table above are inside `data`.

```json
{
  "data": {
    "iso": "2023-10-13T12:00:00+01:00",
    "epoch_seconds": 1697194800,
    "epoch_milliseconds": 1697194800000,
    "detected": "text",
    "matched_format": "%d/%m/%Y %H:%M",
    "timezone": "Europe/Lisbon"
  },
  "errors": null,
  "meta": {
    "request_id": "b9b51694-1cbc-4690-ab73-fa73e681b0dc",
    "timestamp": "2026-10-27T07:19:42.058969Z",
    "version": "2026-03-26"
  },
  "pagination": null
}
```

## Responses

| Status | When it happens |
| --- | --- |
| 200 | Successful Response |
| 400 | The body respects the operation schema, but the use case rejected it. Each problem is one ApiError entry |
| 413 | The request is larger than the request size limit of the API allows |
| 422 | The body does not respect the operation schema. Each problem is one ApiError entry with the code validation_error |
| 500 | Something failed inside the server and was not an input problem. The same envelope, errors may be empty |

---
Source: https://skillfulsardine.com/developers/api/parse-datetime/