Create shared line assignment

curl --request POST \
  --url https://api.photon.codes/v1/projects/{id}/platforms/imessage/assignments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "handle": "<string>",
  "email": "[email protected]",
  "firstName": "<string>",
  "lastName": "<string>"
}
'

import requests

url = "https://api.photon.codes/v1/projects/{id}/platforms/imessage/assignments"

payload = {
    "handle": "<string>",
    "email": "[email protected]",
    "firstName": "<string>",
    "lastName": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    handle: '<string>',
    email: '[email protected]',
    firstName: '<string>',
    lastName: '<string>'
  })
};

fetch('https://api.photon.codes/v1/projects/{id}/platforms/imessage/assignments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.photon.codes/v1/projects/{id}/platforms/imessage/assignments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'handle' => '<string>',
    'email' => '[email protected]',
    'firstName' => '<string>',
    'lastName' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.photon.codes/v1/projects/{id}/platforms/imessage/assignments"

	payload := strings.NewReader("{\n  \"handle\": \"<string>\",\n  \"email\": \"[email protected]\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.photon.codes/v1/projects/{id}/platforms/imessage/assignments")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"handle\": \"<string>\",\n  \"email\": \"[email protected]\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.photon.codes/v1/projects/{id}/platforms/imessage/assignments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"handle\": \"<string>\",\n  \"email\": \"[email protected]\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "assignedPhoneNumber": "<string>",
  "assignmentId": "<string>",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "handle": "<string>",
  "platform": "imessage",
  "projectId": "<string>",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "email": "<string>",
  "firstName": "<string>",
  "lastName": "<string>",
  "releasedAt": "2026-01-01T00:00:00.000Z"
}

{
  "code": "IDEMPOTENCY_KEY_REQUIRED",
  "status": 400,
  "title": "Idempotency Key Required",
  "type": "https://photon.codes/docs/problems/idempotency-key-required"
}

{
  "code": "NOT_AUTHENTICATED",
  "status": 401,
  "title": "Not Authenticated",
  "type": "https://photon.codes/docs/problems/not-authenticated"
}

{
  "code": "FORBIDDEN",
  "status": 403,
  "title": "Forbidden",
  "type": "https://photon.codes/docs/problems/forbidden"
}

{
  "code": "PROJECT_CLOSING",
  "status": 409,
  "title": "Project Is Closing",
  "type": "https://photon.codes/docs/problems/project-closing"
}

{
  "code": "VALIDATION_FAILED",
  "issues": [
    {
      "code": "invalid_type",
      "location": "json",
      "message": "Expected a string.",
      "path": "/name"
    }
  ],
  "status": 422,
  "title": "Request Validation Failed",
  "type": "https://photon.codes/docs/problems/validation-failed"
}

{
  "code": "RATE_LIMITED",
  "status": 429,
  "title": "Too Many Requests",
  "type": "https://photon.codes/docs/problems/rate-limited"
}

{
  "code": "INTERNAL_ERROR",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://photon.codes/docs/problems/internal-error"
}

{
  "code": "UPSTREAM_FAILURE",
  "status": 502,
  "title": "Upstream Service Failure",
  "type": "https://photon.codes/docs/problems/upstream-failure"
}

{
  "code": "BILLING_ENTITLEMENTS_PENDING",
  "status": 503,
  "title": "Billing Entitlements Pending",
  "type": "https://photon.codes/docs/problems/billing-entitlements-pending"
}

{
  "code": "REQUEST_TIMEOUT",
  "status": 504,
  "title": "Request Timeout",
  "type": "https://photon.codes/docs/problems/request-timeout"
}

Shared line assignments

Create shared line assignment

Maps an end user’s iMessage handle — an E.164 phone number or an email address — onto one of the project’s pooled shared iMessage lines, consuming a seat from the project’s entitlement. The assigned number is allocated by the server. When an email address is supplied in email the user is sent an invite asynchronously to that address; it is never inferred from the handle, and the response never reports whether the send succeeded. Requires the platforms:write permission bound to the project resource in the path.

POST

projects

{id}

platforms

imessage

assignments

Create shared line assignment

curl --request POST \
  --url https://api.photon.codes/v1/projects/{id}/platforms/imessage/assignments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "handle": "<string>",
  "email": "[email protected]",
  "firstName": "<string>",
  "lastName": "<string>"
}
'

import requests

url = "https://api.photon.codes/v1/projects/{id}/platforms/imessage/assignments"

payload = {
    "handle": "<string>",
    "email": "[email protected]",
    "firstName": "<string>",
    "lastName": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    handle: '<string>',
    email: '[email protected]',
    firstName: '<string>',
    lastName: '<string>'
  })
};

fetch('https://api.photon.codes/v1/projects/{id}/platforms/imessage/assignments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.photon.codes/v1/projects/{id}/platforms/imessage/assignments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'handle' => '<string>',
    'email' => '[email protected]',
    'firstName' => '<string>',
    'lastName' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.photon.codes/v1/projects/{id}/platforms/imessage/assignments"

	payload := strings.NewReader("{\n  \"handle\": \"<string>\",\n  \"email\": \"[email protected]\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.photon.codes/v1/projects/{id}/platforms/imessage/assignments")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"handle\": \"<string>\",\n  \"email\": \"[email protected]\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.photon.codes/v1/projects/{id}/platforms/imessage/assignments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"handle\": \"<string>\",\n  \"email\": \"[email protected]\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "assignedPhoneNumber": "<string>",
  "assignmentId": "<string>",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "handle": "<string>",
  "platform": "imessage",
  "projectId": "<string>",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "email": "<string>",
  "firstName": "<string>",
  "lastName": "<string>",
  "releasedAt": "2026-01-01T00:00:00.000Z"
}

{
  "code": "IDEMPOTENCY_KEY_REQUIRED",
  "status": 400,
  "title": "Idempotency Key Required",
  "type": "https://photon.codes/docs/problems/idempotency-key-required"
}

{
  "code": "NOT_AUTHENTICATED",
  "status": 401,
  "title": "Not Authenticated",
  "type": "https://photon.codes/docs/problems/not-authenticated"
}

{
  "code": "FORBIDDEN",
  "status": 403,
  "title": "Forbidden",
  "type": "https://photon.codes/docs/problems/forbidden"
}

{
  "code": "PROJECT_CLOSING",
  "status": 409,
  "title": "Project Is Closing",
  "type": "https://photon.codes/docs/problems/project-closing"
}

{
  "code": "VALIDATION_FAILED",
  "issues": [
    {
      "code": "invalid_type",
      "location": "json",
      "message": "Expected a string.",
      "path": "/name"
    }
  ],
  "status": 422,
  "title": "Request Validation Failed",
  "type": "https://photon.codes/docs/problems/validation-failed"
}

{
  "code": "RATE_LIMITED",
  "status": 429,
  "title": "Too Many Requests",
  "type": "https://photon.codes/docs/problems/rate-limited"
}

{
  "code": "INTERNAL_ERROR",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://photon.codes/docs/problems/internal-error"
}

{
  "code": "UPSTREAM_FAILURE",
  "status": 502,
  "title": "Upstream Service Failure",
  "type": "https://photon.codes/docs/problems/upstream-failure"
}

{
  "code": "BILLING_ENTITLEMENTS_PENDING",
  "status": 503,
  "title": "Billing Entitlements Pending",
  "type": "https://photon.codes/docs/problems/billing-entitlements-pending"
}

{
  "code": "REQUEST_TIMEOUT",
  "status": 504,
  "title": "Request Timeout",
  "type": "https://photon.codes/docs/problems/request-timeout"
}

Authorizations

Authorization

string

header

required

Account Service Key, prefixed with pho_ask_, sent as Authorization: Bearer <key>. Acts on behalf of its owning account, subject to the permissions and credential restrictions of each operation. Account access tokens and OAuth grants also use the Bearer header. In organizations that require SSO, Account Service Keys are not accepted for managing the organization's SSO settings, deleting the organization, or checking whether it can be deleted.

Headers

Idempotency-Key

string

required

Identifies one logical mutation across retries.

Required string length: 1 - 255

Pattern: ^[\x21-\x7e]{1,255}$

Path Parameters

string

required

Body

application/json

handle

required

Pattern: ^\+[1-9]\d{1,14}$

string<email>

Maximum string length: 254

Pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

firstName

string

Required string length: 1 - 100

lastName

string

Required string length: 1 - 100

Response

The created shared line assignment.

assignedPhoneNumber

string

required

assignmentId

string

required

createdAt

string<date-time>

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

Example:

"2026-01-01T00:00:00.000Z"

handle

string

required

platform

enum<string>

required

Available options:

imessage,

whatsapp

projectId

string

required

updatedAt

string<date-time>

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

Example:

"2026-01-01T00:00:00.000Z"

string

firstName

string

lastName

string

releasedAt

string<date-time>

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

Example:

"2026-01-01T00:00:00.000Z"

⌘I

Get started

Problems

Endpoints

Event Delivery WebSocket

Event schemas

Create shared line assignment

Authorizations

Headers

Path Parameters

Body

Response