# Overview

Medsender API lets you send/receive faxes, manage fax numbers, send secure email links, create clients, send direct messages and run AI on documents.

## Quickstart: Send your first fax

Use a test key (`sk_test_…`) and a small PDF. This posts to the fax API and returns a token to check status.

#### cURL

```bash
export API_BASE="https://api.medsender.com/api/v2"
export API_KEY="sk_test_..."

# Provision a test fax number (area code 415 as example)
curl -s -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fax_number":{"area_code":"415"}}' \
  "$API_BASE/fax_numbers" | jq

# Send a fax (replace numbers and attach sample.pdf)
curl -s -X POST -H "Authorization: Bearer $API_KEY" \
  -F "file=@./sample.pdf" \
  -F "from_number=+14155550100" \
  -F "to_number=+13125550123" \
  "$API_BASE/sent_faxes"
```

#### Node

```javascript
const API_BASE='https://api.medsender.com/api/v2';
const API_KEY='sk_test_...';

// Provision number
await fetch(`${API_BASE}/fax_numbers`,{
  method:'POST',headers:{Authorization:`Bearer ${API_KEY}`,'Content-Type':'application/json'},
  body:JSON.stringify({fax_number:{area_code:'415'}})
});

// Send fax
const fd=new FormData();
fd.append('file', new Blob([await Deno.readFile('./sample.pdf')]), 'sample.pdf');
fd.append('from_number','+14155550100');
fd.append('to_number','+13125550123');
const res=await fetch(`${API_BASE}/sent_faxes`,{method:'POST',headers:{Authorization:`Bearer ${API_KEY}`},body:fd});
console.log(await res.json());
```

#### TypeScript

```typescript
const API_BASE = 'https://api.medsender.com/api/v2';
const API_KEY: string = 'sk_test_...';

// Provision number
await fetch(`${API_BASE}/fax_numbers`,{
  method:'POST',headers:{Authorization:`Bearer ${API_KEY}`,'Content-Type':'application/json'},
  body:JSON.stringify({fax_number:{area_code:'415'}})
});

// Send fax
const fd = new FormData();
fd.append('file', new Blob([await (await fetch('./sample.pdf')).arrayBuffer()]), 'sample.pdf');
fd.append('from_number','+14155550100');
fd.append('to_number','+13125550123');
const res = await fetch(`${API_BASE}/sent_faxes`,{method:'POST',headers:{Authorization:`Bearer ${API_KEY}`},body:fd});
console.log(await res.json());
```

#### Python

```python
import requests, json
API_BASE='https://api.medsender.com/api/v2'
API_KEY='sk_test_...'

# Provision number
r=requests.post(f"{API_BASE}/fax_numbers", headers={'Authorization':f'Bearer {API_KEY}','Content-Type':'application/json'}, data=json.dumps({'fax_number':{'area_code':'415'}}))
print(r.json())

# Send fax
files={'file':open('./sample.pdf','rb')}
data={'from_number':'+14155550100','to_number':'+13125550123'}
r=requests.post(f"{API_BASE}/sent_faxes", headers={'Authorization':f'Bearer {API_KEY}'}, files=files, data=data)
print(r.json())
```

#### Ruby

```ruby
require 'net/http'
require 'uri'
# Provision number
uri = URI.parse('https://api.medsender.com/api/v2/fax_numbers')
req = Net::HTTP::Post.new(uri)
req['Authorization'] = 'Bearer sk_test_...'
req['Content-Type'] = 'application/json'
req.body = '{"fax_number":{"area_code":"415"}}'
Net::HTTP.start(uri.hostname, uri.port, use_ssl: true){|http| http.request(req)}

# Send fax
uri2 = URI.parse('https://api.medsender.com/api/v2/sent_faxes')
req2 = Net::HTTP::Post.new(uri2)
req2['Authorization'] = 'Bearer sk_test_...'
form = [['file', File.open('sample.pdf')], ['from_number','+14155550100'], ['to_number','+13125550123']]
req2.set_form(form, 'multipart/form-data')
res = Net::HTTP.start(uri2.hostname, uri2.port, use_ssl: true){|http| http.request(req2)}
puts res.body
```

#### PHP

```php
<?php
// Provision number
$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL => 'https://api.medsender.com/api/v2/fax_numbers',
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_...', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['fax_number' => ['area_code' => '415']]),
  CURLOPT_RETURNTRANSFER => true
]);
curl_exec($ch);

// Send fax
$post = [
  'file' => new CURLFile('sample.pdf', 'application/pdf', 'sample.pdf'),
  'from_number' => '+14155550100',
  'to_number' => '+13125550123'
];
curl_setopt_array($ch, [
  CURLOPT_URL => 'https://api.medsender.com/api/v2/sent_faxes',
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_...'],
  CURLOPT_POSTFIELDS => $post,
  CURLOPT_RETURNTRANSFER => true
]);
$res = curl_exec($ch);
echo $res;
```

#### Java

```java
import java.net.http.*;
import java.net.URI;
public class Quickstart {
  public static void main(String[] args) throws Exception {
    var client = HttpClient.newHttpClient();
    // Provision number (JSON)
    var pbody = "{\"fax_number\":{\"area_code\":\"415\"}}";
    var preq = HttpRequest.newBuilder()
      .uri(URI.create("https://api.medsender.com/api/v2/fax_numbers"))
      .header("Authorization","Bearer sk_test_...")
      .header("Content-Type","application/json")
      .POST(HttpRequest.BodyPublishers.ofString(pbody))
      .build();
    client.send(preq, HttpResponse.BodyHandlers.ofString());
    // Send fax (simplified placeholder)
    var req = HttpRequest.newBuilder()
      .uri(URI.create("https://api.medsender.com/api/v2/sent_faxes"))
      .header("Authorization","Bearer sk_test_...")
      .POST(HttpRequest.BodyPublishers.ofString(""))
      .build();
    var res = client.send(req, HttpResponse.BodyHandlers.ofString());
    System.out.println(res.body());
  }
}
```

#### C#

```csharp
using System;
using System.Net.Http;
using System.Threading.Tasks;
// Provision number
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization","Bearer sk_test_...");
var json = "{\"fax_number\":{\"area_code\":\"415\"}}";
await client.PostAsync("https://api.medsender.com/api/v2/fax_numbers", new StringContent(json, System.Text.Encoding.UTF8, "application/json"));
// Send fax (simplified placeholder)
var res = await client.PostAsync("https://api.medsender.com/api/v2/sent_faxes", new StringContent(""));
Console.WriteLine(await res.Content.ReadAsStringAsync());
```

### Endpoints (Customer)

- Sent Faxes: `GET /sent_faxes`, `GET /sent_faxes/:id`, `POST /sent_faxes`
- Received Faxes: `GET /received_faxes`, `GET /received_faxes/:id`, `POST /received_faxes/test_receive`, `POST /received_faxes/:id/forward_as_fax`
- Fax Numbers: `GET /fax_numbers`, `GET /fax_numbers/:slug`, `POST /fax_numbers`, `PATCH /fax_numbers/:slug`
- Emails (secure links): `POST /emails`, `GET /emails/:id`
- Clients: `GET /clients`, `GET /clients/:client_id`, `POST /clients`, `PATCH /clients/:client_id`
- Direct Messages: `POST /direct_messages`
- AI Documents: `POST /ai_documents`, `GET /ai_documents`, `GET /ai_documents/:id`

All calls use `Authorization: Bearer sk_*` with your API key. Test keys start with `sk_test_`.

### Response Examples

Create (Send Fax)

```json
{ "message": "Record has been sent, we will send a callback upon completion.", "fax_id": "abc123" }
```

List (Fax Numbers)

```json
{ "fax_numbers": [{ "id": "uuid", "number": "+1..." }] }
```