API Documentation

Integrate with Cinema Jobs to access job listings, company data, and more

Quick Start

Get up and running with our API in minutes

1. Get API Key

2. Make Request

Use our RESTful API to fetch job listings and company data

3. Integrate

Integrate the data into your application or website

Base URL

https://api.cinemajobs.com/v1

All API requests should be made to this base URL. The API uses HTTPS and requires authentication for most endpoints.

Authentication

Choose the authentication method that works best for your application

API Key

Medium Security

Simple authentication using an API key in the request header

Authorization: Bearer your-api-key-here

OAuth 2.0

High Security

Secure authentication using OAuth 2.0 flow

Authorization: Bearer oauth-access-token

JWT Token

High Security

JSON Web Token authentication for stateless authentication

Authorization: Bearer jwt-token-here

API Endpoints

Explore our comprehensive API endpoints

GET

/api/jobs

Retrieve job listings with filtering and pagination

Parameters

Name	Type	Required	Description
page	integer	Optional	Page number for pagination
limit	integer	Optional	Number of jobs per page (max 100)
location	string	Optional	Filter by location
category	string	Optional	Filter by job category
company	string	Optional	Filter by company name

Example

Request

GET /api/jobs?location=London&category=management&page=1&limit=20

Response

{
  "data": [
    {
      "id": 1,
      "title": "Cinema Manager",
      "company": "Cineworld",
      "location": "London, UK",
      "salary": "£35,000 - £45,000",
      "type": "Full-time",
      "posted": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

GET

/api/jobs/{id}

Retrieve detailed information about a specific job

Parameters

Name	Type	Required	Description
id	integer	Required	Job ID

Example

Request

GET /api/jobs/123

Response

{
  "id": 123,
  "title": "Cinema Manager",
  "company": {
    "id": 45,
    "name": "Cineworld",
    "logo": "https://example.com/logo.png"
  },
  "location": "London, UK",
  "salary": "£35,000 - £45,000",
  "type": "Full-time",
  "description": "We are looking for an experienced Cinema Manager...",
  "requirements": [
    "3+ years management experience",
    "Cinema industry knowledge"
  ],
  "benefits": [
    "Health insurance",
    "Pension scheme",
    "Free cinema tickets"
  ],
  "posted": "2024-01-15T10:00:00Z",
  "expires": "2024-02-15T10:00:00Z"
}

GET

/api/companies

Retrieve company listings

Parameters

Name	Type	Required	Description
page	integer	Optional	Page number for pagination
limit	integer	Optional	Number of companies per page
location	string	Optional	Filter by location
size	string	Optional	Filter by company size

Example

Request

GET /api/companies?location=London&size=large

Response

{
  "data": [
    {
      "id": 45,
      "name": "Cineworld",
      "logo": "https://example.com/logo.png",
      "location": "London, UK",
      "size": "1000+ employees",
      "industry": "Cinema Exhibition",
      "website": "https://cineworld.co.uk"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "pages": 3
  }
}

POST

/api/jobs

Create a new job posting (requires authentication)

Parameters

Name	Type	Required	Description
title	string	Required	Job title
company_id	integer	Required	Company ID
location	string	Required	Job location
description	string	Required	Job description
salary	string	Optional	Salary range
type	string	Required	Job type (full-time, part-time, contract)

Example

Request

POST /api/jobs

Response

{
  "id": 124,
  "title": "Cinema Manager",
  "status": "pending",
  "message": "Job posting created successfully and is pending approval"
}

Rate Limits

To ensure fair usage and maintain service quality, we implement rate limits on our API endpoints.

Endpoint	Limit	Burst
GET /api/jobs	1000 requests/hour	100 requests/minute
GET /api/companies	500 requests/hour	50 requests/minute
POST /api/jobs	100 requests/hour	10 requests/minute
All other endpoints	200 requests/hour	20 requests/minute

Error Codes

Our API uses standard HTTP status codes to indicate success or failure of requests.

400Bad Request

Invalid request parameters or malformed JSON

401Unauthorized

Missing or invalid authentication credentials

403Forbidden

Valid credentials but insufficient permissions

404Not Found

Requested resource does not exist

429Too Many Requests

Rate limit exceeded

500Internal Server Error

Unexpected server error

SDKs and Libraries

Use our official SDKs to integrate with your preferred programming language

JavaScript

Official SDK for JavaScript

Python

Official SDK for Python

PHP

Official SDK for PHP

Java

Official SDK for Java

Need Help with Integration?

Our developer support team is here to help you integrate with our API successfully.