REST API

Your agency: branding, contacts, plan features and current usage. Handy as a connectivity check.

Request

curl -H "Authorization: Bearer $CASTINGS_TOKEN" https://castings.com.ua/api/v1/agency

Response

{
  "data": {
    "id": 11,
    "name": "Star Casting",
    "slug": "star-casting",
    "logo_url": "https://…/storage/logos/star.webp",
    "public_url": "https://star-casting.castings.com.ua",
    "contacts": { "email": "hi@star.example", "phone": "+380…" },
    "plan": { "name": "Basic", "expires_at": "2026-09-01T00:00:00+00:00", "active": true },
    "features": { "web_intake": true, "email_intake": true, "telegram_intake": true,
                  "subdomain": true, "pdf_export": true },
    "limits": { "castings_this_month": 4, "castings_per_month": 30,
                "applications_this_month": 128, "applications_per_month": 0,
                "max_photo_mb": 30, "max_video_mb": 1024 }
  }
}

Your published castings, newest first. Drafts are never returned.

Parameters

Request

curl -H "Authorization: Bearer $CASTINGS_TOKEN" \
     "https://castings.com.ua/api/v1/castings?status=open&gender=female&per_page=10"

Response

{
  "data": [
    {
      "id": 1474,
      "role_name": "Blanchet",
      "excerpt": "Lead role in the feature film…",
      "gender": "female",
      "age_min": 20,
      "age_max": 35,
      "is_open": true,
      "published_at": "2026-06-26T00:00:00+00:00",
      "closes_at": null,
      "public_url": "https://castings.com.ua/casting/1474"
    }
  ],
  "meta": { "page": 1, "per_page": 10, "total": 23, "last_page": 3 }
}

One casting with its full description, images and application fields.

Request

curl -H "Authorization: Bearer $CASTINGS_TOKEN" https://castings.com.ua/api/v1/castings/1474

Response

{
  "data": {
    "id": 1474,
    "role_name": "Blanchet",
    "description": "Full text of the casting call…",
    "project": "A Man Escaped",
    "gender": "female",
    "age_min": 20,
    "age_max": 35,
    "is_open": true,
    "closes_at": "2026-09-30T00:00:00+00:00",
    "public_url": "https://castings.com.ua/casting/1474",
    "images": [
      { "url": "https://…/o/photo.webp", "thumb_url": "https://…/360/photo.webp" }
    ],
    "fields": [
      { "key": "first_name", "label": "First Name", "type": "string",
        "required": true, "photos_min_count": null, "photos_max_count": null }
    ]
  }
}

Just the application form definition — what to render and where to submit it.

Request

curl -H "Authorization: Bearer $CASTINGS_TOKEN" https://castings.com.ua/api/v1/castings/1474/fields

Response

{
  "data": {
    "casting_id": 1474,
    "accepts_applications": true,
    "submit_url": "https://castings.com.ua/api/v1/castings/1474/applications",
    "max_photo_mb": 30,
    "max_video_mb": 1024,
    "fields": [
      { "key": "first_name", "label": "First Name", "type": "string", "required": true,
        "photos_min_count": null, "photos_max_count": null },
      { "key": "photos", "label": "Photos", "type": "file[]", "required": true,
        "photos_min_count": 2, "photos_max_count": 6 }
    ]
  }
}

Submit an application. Send multipart/form-data whenever the payload carries photos or a video file; plain form fields or JSON work otherwise.

Parameters

Request

curl -X POST \
     -H "Authorization: Bearer $CASTINGS_TOKEN" \
     -F "first_name=Anna" \
     -F "last_name=Kovalenko" \
     -F "email=anna@example.com" \
     -F "age=24" \
     -F "phone=+380501112233" \
     -F "photos[]=@portrait.jpg" \
     -F "photos[]=@fullheight.jpg" \
     https://castings.com.ua/api/v1/castings/1474/applications

Response

HTTP/1.1 201 Created

{
  "data": {
    "id": 37405,
    "casting": { "id": 1474, "role_name": "Blanchet" },
    "status": "pending",
    "source": "web",
    "submitted_at": "2026-08-01T07:23:34+00:00",
    "fields": {
      "first_name": { "label": "First Name", "value": "Anna" },
      "photos": { "label": "Photos", "value": [
        { "url": "https://…/o/a.webp", "thumb_url": "https://…/360/a.webp" }
      ] }
    }
  }
}

Applications received across your castings, newest first, whatever channel they arrived through (web, email, Telegram, added by a director).

Parameters

Request

curl -H "Authorization: Bearer $CASTINGS_TOKEN" \
     "https://castings.com.ua/api/v1/applications?casting_id=1474&status=pending&since=2026-07-01"

Response

{
  "data": [
    {
      "id": 37405,
      "casting": { "id": 1474, "role_name": "Blanchet" },
      "status": "pending",
      "source": "web",
      "submitted_at": "2026-08-01T07:23:34+00:00",
      "fields": { "first_name": { "label": "First Name", "value": "Anna" } }
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 1, "last_page": 1 }
}

A single application with all submitted answers and media URLs.

Request

curl -H "Authorization: Bearer $CASTINGS_TOKEN" https://castings.com.ua/api/v1/applications/37405

Your agency's own talent database — the profiles your directors maintain. Talents registered on the platform are not exposed here.

Parameters

Request

curl -H "Authorization: Bearer $CASTINGS_TOKEN" \
     "https://castings.com.ua/api/v1/talents?gender=female&age_min=18&age_max=30&per_page=24"

Response

{
  "data": [
    {
      "id": 1441,
      "display_name": "Maurice Beerblock",
      "first_name": "Maurice",
      "last_name": "Beerblock",
      "age": 32,
      "gender": "male",
      "height": 184,
      "thumb_url": "https://…/360/portrait.webp",
      "photo_url": "https://…/o/portrait.webp"
    }
  ],
  "meta": { "page": 1, "per_page": 24, "total": 477, "last_page": 20 }
}

A full talent card: measurements, appearance, bio, skills, photo gallery and converted videos.

Request

curl -H "Authorization: Bearer $CASTINGS_TOKEN" "https://castings.com.ua/api/v1/talents/1441?include=contacts"

Response

{
  "data": {
    "id": 1441,
    "display_name": "Maurice Beerblock",
    "age": 32,
    "gender": "male",
    "height": 184, "weight": 78, "bust": 96, "waist": 80, "hips": 94,
    "shoe_size": "43", "clothing_size": "48",
    "eye_color": "brown", "hair_color": "dark_brown",
    "bio": "Theatre and film actor…",
    "skills": ["horse riding", "fencing"],
    "photos": [
      { "id": 90, "url": "https://…/o/a.webp", "thumb_url": "https://…/360/a.webp", "is_title": true }
    ],
    "videos": [
      { "id": 12, "url": "https://…/cloud/demo.mp4",
        "poster_url": "https://…/cloud/demo.webp", "type": "demo", "is_youtube": false }
    ],
    "contacts": { "phone": "+380…", "email": "maurice@example.com",
                  "telegram": "@maurice", "viber": null, "whatsapp": null, "social_links": [] }
  }
}

The agency behind the token: branding, contacts, plan features and current usage.

ReturnsThe agency record (the `data` object of GET /agency).

$agency = $client->agency();
echo $agency['name'];                          // "Star Casting"
echo $agency['features']['web_intake'];        // true
echo $agency['limits']['applications_this_month'];  // 128

# Python
agency = client.agency()
print(agency["plan"]["name"], agency["plan"]["expires_at"])

Connectivity + credentials check. Swallows every API error and answers with a boolean — handy for a health check or a settings screen.

Returnstrue when the token works, false on any error.

if (! $client->ping()) {
    exit('Check CASTINGS_TOKEN — the API rejected it.');
}

# Python
assert client.ping(), "Check CASTINGS_TOKEN"

One page of your published castings, newest first. Drafts never appear.

Parameters

ReturnsA page of casting summaries: id, role_name, excerpt, gender, age_min, age_max, is_open, published_at, closes_at, public_url.

$page = $client->castings(['status' => 'open', 'gender' => 'female', 'per_page' => 10]);

foreach ($page as $casting) {
    printf("#%d %s (%s)\n", $casting['id'], $casting['role_name'],
           $casting['is_open'] ? 'open' : 'closed');
}
echo $page->total(), ' castings in total';

# Python
page = client.castings(status="open", gender="female", per_page=10)
for casting in page:
    print(casting["id"], casting["role_name"])
print(page.total, "castings in total")

The same filters, but every page — fetched lazily as you consume the sequence, so memory stays flat on large catalogues.

ReturnsA generator/iterator of casting summaries.

foreach ($client->allCastings(['status' => 'all']) as $casting) {
    $csv->write([$casting['id'], $casting['role_name']]);
}

# Python
for casting in client.iter_castings(status="all"):
    writer.writerow([casting["id"], casting["role_name"]])

One casting in full: description, project, images and the application fields.

Parameters

ReturnsThe casting record, including images[] (url, thumb_url) and fields[].

RaisesCastingsNotFoundException / CastingsNotFoundError

$casting = $client->casting(1474);
echo $casting['description'];
echo $casting['images'][0]['url'] ?? 'no images';

# Python
casting = client.casting(1474)
print(casting["project"], len(casting["images"]), "images")

The application form definition — everything needed to render a form and know where to send it.

Parameters

Returnscasting_id, accepts_applications (bool), submit_url, max_photo_mb, max_video_mb and fields[] with key, label, type, required, photos_min_count, photos_max_count.

$form = $client->castingFields(1474);

if (! $form['accepts_applications']) {
    exit('This casting is closed.');
}

foreach ($form['fields'] as $field) {
    printf("%-16s %-8s %s\n", $field['key'], $field['type'],
           $field['required'] ? 'required' : 'optional');
}
// first_name       string   required
// photos           file[]   required

# Python
form = client.casting_fields(1474)
required = [f["key"] for f in form["fields"] if f["required"]]

Submit an application. Files are sent as multipart; a list of photos is indexed automatically so the server receives a proper array.

Parameters

ReturnsThe created (or updated) application: id, casting, status, source, submitted_at and fields with the stored values — media expanded into URLs.

RaisesCastingsDuplicateException/Error (409), CastingsValidationException/Error (422), CastingsRateLimitException/Error (429)

$application = $client->apply(1474, [
    'first_name' => 'Anna',
    'email'      => 'anna@example.com',
    'age'        => 24,
], [
    'photos'          => ['/tmp/portrait.jpg', '/tmp/fullheight.jpg'],
    'video_demo_file' => '/tmp/reel.mp4',
]);

echo $application['id'];                                   // 37405
echo $application['fields']['photos']['value'][0]['url'];   // https://…/o/a.webp

# Python — handle the repeat submission
try:
    client.apply(1474, fields, files={"photos": paths})
except CastingsDuplicateError:
    client.apply(1474, fields, update_existing=True)

Applications received across your castings, newest first — whatever channel they arrived through.

Parameters

ReturnsA page of applications with their submitted answers.

$new = $client->applications(['status' => 'pending', 'since' => '2026-08-01']);

foreach ($new as $application) {
    echo $application['fields']['email']['value'] ?? '—', PHP_EOL;
}

# Python
for app in client.applications(casting_id=1474, source="web"):
    print(app["id"], app["submitted_at"])

Every application matching the filters, paging for you — the shape to use when syncing into your own CRM.

ReturnsA generator/iterator of applications.

foreach ($client->allApplications(['since' => $lastSyncedAt]) as $application) {
    $crm->upsert($application);
}

# Python
for application in client.iter_applications(since=last_synced_at):
    crm.upsert(application)

A single application with all answers and absolute media URLs.

Parameters

ReturnsThe application record.

RaisesCastingsNotFoundException / CastingsNotFoundError

$application = $client->application(37405);

foreach ($application['fields'] as $key => $field) {
    echo $field['label'], ': ', is_array($field['value']) ? '[media]' : $field['value'], PHP_EOL;
}

# Python
application = client.application(37405)
photos = application["fields"].get("photos", {}).get("value", [])

One page of your agency's own talent database. Profiles with a title photo come first, so a gallery looks right without extra sorting.

Parameters

ReturnsA page of talent summaries: id, display_name, first_name, last_name, age, gender, height, thumb_url, photo_url.

$models = $client->talents(['gender' => 'female', 'age_min' => 18, 'per_page' => 24]);

foreach ($models as $talent) {
    printf('<img src="%s" alt="%s">', $talent['thumb_url'], $talent['display_name']);
}

# Python
for talent in client.talents(height_min=175, per_page=24):
    print(talent["display_name"], talent["height"])

Your whole talent base, page by page — for nightly exports or a static site build.

ReturnsA generator/iterator of talent summaries.

foreach ($client->allTalents() as $talent) {
    $index->add($talent['id'], $talent['display_name']);
}

# Python
everyone = list(client.iter_talents())

A full talent card. Contacts stay out of the response unless you ask for them — leave them off on a public page.

Parameters

ReturnsMeasurements, appearance, bio, skills, experience, education, photos[] and videos[] (converted uploads and YouTube links).

RaisesCastingsNotFoundException / CastingsNotFoundError

$talent = $client->talent(1441, withContacts: true);

echo $talent['display_name'], ', ', $talent['age'];
echo $talent['contacts']['phone'];
echo count($talent['photos']), ' photos, ', count($talent['videos']), ' videos';

# Python — public page, no contacts
talent = client.talent(1441)
gallery = [p["thumb_url"] for p in talent["photos"]]