NAV
shell

Introduction

Filmmakers provides a RESTful JSON API with token-based authentication. You can request an API key with our support. The permission scope of the API key varies depending on the use case, so when contacting us be sure to specify the desired use case (e.g. you plan on using Filmmakers data for a website).

Authentication

Once you have been issued an API key you can use the following code to authorize requests:

curl "api_endpoint_here" \
  -H "Authorization: Token token=API_KEY"

Filmmakers expects the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Token token=API_KEY

Cross origin resource sharing

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin.

Here's a sample request sent from a browser hitting https://www.example.com/:

$ curl -I https://www.filmmakers.eu/api/v1/actor_profiles -H "Origin: https://www.example.com"
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET

Rate limits

Rate limits are enforced on a per IP address basis. Currently Filmmakers allows up to 300 requests within a 5 minute period. If this quota is exceeded your IP will be throttled for the remainder of this period. In this case the API will return an error responses that shows up as status code 429.

Along with the status code the following RateLimit response header fields will be returned:

Ratelimit-Limit: 300
Ratelimit-Remaining: 0
Ratelimit-Reset: 1597048500

Webhooks

A webhook is an endpoint on your server that receives requests from Filmmakers, notifying you about events for actor profiles such as a profile edit. This requires a new endpoint on your server such as https://www.example.com/webhooks/filmmakers which should be publicly accessible and allow unauthenticated POST requests. Note that HTTPS URLs are required for all webhook endpoints.

Read the event data

Filmmakers sends the event data in the request body. Each event is structured as an Event object with a type, timestamp, and related Filmmakers resource nested under data (currently only an actor profile id - see example on the right)

{
  "type": "actor_profile.updated"
  "created": 1633887337,
  "data": {
    "id": 123
  }
}

There are currently two event types: actor_profile.updated and actor_profile.deleted. Note that update events are grouped if they occur within a reasonable timeframe, e.g. you might only receive 1 webhook if an actor profile is updated several times within a short timeframe.

Return a 200 response

Send a successful 200 response to Filmmakers as quickly as possible because the event is retried with an exponential back off if a response isn't sent within a reasonable time. This means that you should write any long-running processes as code that can run asynchronously outside the webhook endpoint.

Verify requests are sent by Filmmakers

X-Signature: t=1492774577, v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

All webhook events are signed by including a signature in each event's header. This allows you to verify that the events were sent by Filmmakers, not by a third party. The Api key is used as secret to sign webhook events. Signatures are generated using a hash-based message authentication code (HMAC) with SHA-256.

The X-Signature header included in each signed event contains a timestamp and one signature. The timestamp is prefixed by t=, and the signature is prefixed by a scheme. Schemes start with v, followed by an integer. Currently, the only signature scheme is v1.

You can verify the signature on your side as follows (see example on the right in Ruby):

# Step 1: Extract the timestamp and signatures from the header
signature = request.headers["X-Signature"]
  .split(",")
  .map { |part| part.split("=") }
  .to_h
# (this returns a hash like { "t" => 1492774577, "v1" => "5257a86..." })

# Step 2: Prepare the signed_payload string
payload = request.body.read
signed_payload = "#{signature['t']}.#{payload}"

# Step 3: Determine the expected signature
expected_signature = OpenSSL::HMAC.hexdigest(
  OpenSSL::Digest.new("sha256"),
  "YOUR_FILMMAKERS_API_KEY",
  signed_payload
)

# Step 4: Compare the signatures
expected_signature == signature["v1"]

⚠ Webhooks are not yet generally available. If you are interested in using them please contact our support

Changelog

Actor profiles

Get all actor profiles

curl "https://www.filmmakers.eu/api/v1/actor_profiles" \
  -H "Authorization: Token token=API_KEY"

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "name": "John Doe",
    "gender": "m"
  },
  {
    "id": 2,
    "name": "Jane Doe",
    "gender": "f"
  }
]

This endpoint retrieves all actor profiles available with the access rights of the API key. Most of the time it is scoped to a talent agency.

Pagination

This API endpoint is paginated, following the proposed RFC-8288 standard for Web linking.

The pagination information is included in response HTTP headers, namely Total (total entries), Per-Page (entries per page) and Link (containing links to corresponding pages). The current page can be set using the page-parameter.

HTTP Request

GET https://www.filmmakers.eu/api/v1/actor_profiles

Query Parameters

Parameter Default Description
page 1 Page to display - see "Pagination" above
include_picture false If set to true, the result will include the profile picture thumbnail in a field named main_picture_url_tile.
picture_version null Can be set to original, large or thumb to change the included picture version. The picture will be included in a field named picture_url. (Only applies if include_picture is true)
fields name,gender Can be used to modify the fields included in the response. Possible values are: age, gender, first_name, last_name, name, professions, languages, representative, updated_at.
order id Changes the order of returned results. Possible values are: id, name, last_name
gender null Allows filtering by gender. Possible values are: m, f, i.

Response fields

Field Type Description
id number Unique ID of the actor profile
age number
gender string f for female, m for male, i for diverse
name string Full name (ie. first & last name) name can be retrieved separately by using the fields parameter
first_name string
last_name string
professions array of strings list of professions, eg. ["schauspieler", "synchronsprecher"]
languages JSON Object format { "language": "skill level" }
updated_at string format ISO 8601
main_picture_url_tile string profile picture url (thumbnail version)
picture_url string profile picture url of specified version
picture_copyright string copyright information for the profile picture
representative JSON Object "id" and "name" of the agent representing the actor

Get a specific actor profile

curl "https://www.filmmakers.eu/api/v1/actor_profiles/123" \
  -H "Authorization: Token token=API_KEY"

The above command returns JSON structured like this:

{
  "id": 162,
  "first_name": "John",
  "last_name": "Doe",
  "filmmakers_url": "https://www.filmmakers.eu/actors/john-doe",
  "filmmakers_cd_url": "https://cd.filmmakers.eu/profil/castupload/162",
  "acting_age_from": 35,
  "acting_age_to": 45,
  "year_of_birth": 1980,
  "age": 41,
  "height": 170,
  "weight": 60,
  "state_code": "DE-RP",
  "accommodation_options": [
    "Berlin",
    "Frankfurt",
    "Köln"
  ],
  "homepage_url": "www.example.com",
  "imdb_link": "https://www.imdb.com/name/nm0000001",
  "imdb_id": "nm0000001",
  "facebook_page": "Filmmakers",
  "twitter_handle": "Filmmakers",
  "instagram_username": "Filmmakers",
  "filmmakers_url": null,
  "sv_url": null,
  "wikipedia_url": "https://de.wikipedia.org/wiki/My_Page",
  "agency_profile_url": "https://www.my-agency/my-profile",
  "talent_agency_id": 1,
  "representative": {
    "id": 123,
    "name": "Jane Roe"
  },
  "updated_at": "2021-06-22T16:14:11.519+02:00",
  "native_dialect": "rheinisch",
  "place_of_birth": "Darmstadt",
  "city": "Mainz",
  "gender": "m",
  "eye_color": "braun",
  "hair_color": "braun",
  "hair_length": "mittel",
  "ethnic_appearances": [
    "mitteleuropaisch"
  ],
  "figure": "normal",
  "pitch": "bariton",
  "nationalities": [
    "DE"
  ],
  "languages": {
    "deutsch": "muttersprachlich",
    "englisch": "fliessend"
  },
  "dialects": {
    "hessisch": "kann",
    "rheinisch": "kann"
  },
  "accents": {
    "osterreichisch": "kann"
  },
  "instruments": {
    "gitarre": "gut"
  },
  "sports": [
    "buhnenkampf"
  ],
  "dances": {
    "freestyle": "gut"
  },
  "professions": [
    "schauspieler"
  ],
  "singing": {
    "jazz": "grundkenntnisse"
  },
  "drivers_licenses": [
    "pkw-klasse-b-be"
  ],
  "licenses": [
    "fallschirmspringer-lizenz"
  ],
  "country": "DE",
  "state": "DE-RP",
  "special_skills": {
    "403": "gut"
  },
  "unions": [
    "bffs"
  ],
  "pictures": [
    {
      "id": 140,
      "copyright": "Jane Doe",
      "created_at": "2021-06-21T16:18:41.087+02:00",
      "url": "https://static.filmmakers.eu/production/b6ac24ef-7bbc-4486-bfc9-89fdce3a9fde.png",
      "versions": {
        "original": "https://static.filmmakers.eu/production/b6ac24ef-7bbc-4486-bfc9-89fdce3a9fde.png",
        "large": "https://d205pfv3qf1itp.cloudfront.net/s3/castupload-com/production/b6ac24ef-7bbc-4486-bfc9-89fdce3a9fde.png/755095922e94f912e6691c63f7aef9887d069f13c5dc84b581bbabea6761f7d5/c_limit,f_jpg,h_1200,q_80,w_1200",
        "thumb": "https://d205pfv3qf1itp.cloudfront.net/s3/castupload-com/production/b6ac24ef-7bbc-4486-bfc9-89fdce3a9fde.png/8cbb163eb48e440b5e9715e0c551180817f76c7072fd205df3c320bae08548e8/c_crop,f_jpg,h_370,q_80,w_370,x_0,y_0/c_fill,g_North,h_190,w_190"
      },
      "orientation": "square",
      "dimensions": [
        370,
        370
      ],
      "crop_coordinates": {
        "x": 0,
        "y": 0,
        "w": 500,
        "h": 500
      },
      "main_picture": true,
      "year": 2021,
      "recorded_at": "2020-06-22T11:51:51.363+02:00"
    },
    {
      "id": 141,
      "copyright": "",
      "created_at": "2021-06-21T16:18:47.460+02:00",
      "url": "https://static.filmmakers.eu/production/5c5a1832-3ee4-495d-bfb0-03694dab0bd2.png",
      "versions": {
        "original": "https://static.filmmakers.eu/production/5c5a1832-3ee4-495d-bfb0-03694dab0bd2.png",
        "large": "https://d205pfv3qf1itp.cloudfront.net/s3/castupload-com/production/5c5a1832-3ee4-495d-bfb0-03694dab0bd2.png/c323525480481e940c6b95eced100afa1b3c23ef2af4431df592b0e492de2211/c_limit,f_jpg,h_1200,q_80,w_1200",
        "thumb": "https://d205pfv3qf1itp.cloudfront.net/s3/castupload-com/production/5c5a1832-3ee4-495d-bfb0-03694dab0bd2.png/e63279986f8a8b40f0d1a99bb14c69918a749a34750248578a95ee17fdc58da7/c_fill,f_jpg,g_North,h_190,q_80,w_190"
      },
      "orientation": "landscape",
      "dimensions": [
        365,
        360
      ],
      "main_picture": false,
      "year": 2021,
      "recorded_at": null
    }
  ],
  "external_showreel": "https://www.youtube.com/watch?v=xxxx",
  "external_showreels": [
    "https://www.youtube.com/watch?v=xxxx",
    "https://vimeo.com/xxxx"
  ],
  "showreels": [
    {
      "name": "Showreel 2021",
      "url": "https://www.filmmakers.eu/actors/john-doe/showreels/15",
      "type": "video"
    },
    {
      "name": "Showreel 2020",
      "url": "https://www.filmmakers.eu/actors/john-doe/showreels/16",
      "type": "video"
    },
    {
      "name":"Audioreel 2021",
      "url":"https://www.filmmakers.eu/actors/john-doe/showreels/17",
      "type":"audio"
    }
  ],
  "vita": {
    "primary_education": [
      {
        "name": "ABC School",
        "year_from": 2012
      }
    ],
    "award": [
      {
        "info": "",
        "name": "Avanca Film Festival - Best Performance",
        "year_from": 2017,
        "year_to": 2017,
        "award_nominated": true
      }
    ],
    "education": [
      {
        "info": "",
        "name": "123 School",
        "year_from": 2013,
        "year_to": 2014
      }
    ],
    "film": [
      {
        "info": "",
        "name": "Schneeflöckchen",
        "year_from": 2019,
        "year_to": 2020,
        "role": "Jack",
        "role_type": "supporting",
        "distributor": "",
        "director": "Adolfo Kolmerer",
        "producer": "",
        "caster": ""
      },
      {
        "info": "",
        "name": "The Harmonica ",
        "year_from": 2018,
        "year_to": 2018,
        "role": "Felix",
        "role_type": "leading",
        "distributor": "",
        "director": "",
        "producer": "Deutsche Film- und Fernsehakademie Berlin",
        "caster": ""
      }
    ],
    "television": [
      {
        "info": "",
        "name": "Mord mit Aussicht",
        "year_from": 2015,
        "year_to": 2016,
        "role": "Robert",
        "role_type": "misc",
        "distributor": "",
        "director": "",
        "producer": "",
        "caster": ""
      }
    ],
    "theatre": [],
    "audio": [],
    "other": [],
    "internet": [],
    "commercial": []
  }
}

This endpoint retrieves a specific actor profile.

HTTP Request

GET https://www.filmmakers.eu/api/v1/actor_profiles/<ID>

URL Parameters

Parameter Description
ID The ID of the actor profile to retrieve

Query Parameters

Parameter Default Description
enum null If set to translate attributes are translated if possible (e.g. gender will be male or männlich instead of m). Note that hash and array attributes (eg. dances / sports) will be joined to a comma-separated string when translating attributes.
locale en Translates attributes with closed lists, free text fields are only available in the entry language. Possible values are: en, de, fr, it, es, pl, ro, ru, tr. This parameter only has an effect when enum is set to translate.

Response fields

See example response to the right for an overview of included fields. Please note:

Talent agencies

Get talent agency data

curl "https://www.filmmakers.eu/api/v1/talent_agencies/123" \
  -H "Authorization: Token token=API_KEY"

The above command returns JSON structured like this:

{
  "id": 1,
  "name": "Example agency",
  "homepage_url": "https://www.example.com",
  "imdb_link": "https://pro.imdb.com/company/co0000001",
  "imdb_id": "co0000001",
  "showreel_url": "https://www.example.com/showreel",
  "twitter_handle": "@example_agency",
  "public_email": "info@example.com",
  "picture_url": "https://static.filmmakers.eu/example.png",
  "address": {
    "city": "Mainz",
    "country": "DE",
    "fax": null,
    "line1": "Wallstr. 11",
    "line2": "",
    "phone": "49613163691950",
    "zipcode": "55122"
  }
}

This endpoint retrieves a specific talent agency.

HTTP Request

GET https://www.filmmakers.eu/api/v1/talent_agencies/<ID>

URL Parameters

Parameter Description
ID The ID of the talent agency to retrieve

Response fields

See example response to the right for an overview of included fields.

Attributes

Get all attributes

curl "https://www.filmmakers.eu/api/v1/attributes/" \
  -H "Authorization: Token token=API_KEY"

The above command returns an Array structured like this:

[
  "accent_skill",
  "accents",
  "dances",
  "dialect_skill",
  "dialects",
  "drivers_licenses",
  ...
]

This endpoint retrieves all possible profile attributes that are closed lists like languages or nationalities as well as attributes for credits/vita.

For countries ISO 3166-1 alpha-2 codes are used https://en.wikipedia.org/wiki/ISO_3166-2. For federal states (states/subdivisions) ISO 3166-2 are used, e.g. for Germany: https://en.wikipedia.org/wiki/ISO_3166-2:DE. Since the ISO lists are standardized (and extensive), they are not present in this endpoint for the time being.

Get key/value pairs for attributes

curl "https://www.filmmakers.eu/api/v1/attributes/xxx" \
  -H "Authorization: Token token=API_KEY"

The above command returns JSON structured like this (e.g. for nationalities):

{
  "AD":"Andorran",
  "AE":"United Arab Emirates",
  "AF":"Afghan",
  "AG":"Antigua and Barbuda",
  "AL":"Albanian",
  "AM":"Armenian",
  "AO":"Angolan",
  "AR":"Argentinean",
  "AT":"Austrian",
  "AU":"Australian",
  ...
}

This endpoint retrieves all possible key/value pair for one of the attributes. Pass one of the supported locales (see above) as param to retrieve localized values.

shell