Developer documentation

Job Feed API

Pull Ocean Blue Corporation's live job listings directly into your platform. Real-time REST API, authenticated with API keys, versioned, and ready to integrate.

Real-time data
API key auth
REST / JSON

Overview

The Ocean Blue Corporation Job Feed API lets external platforms pull our live job listings. It's a versioned REST API hosted at /api/v1 and returns JSON.

Base URL

https://oceanbluecorp.com/api/v1

Format

JSON, all requests and responses

Auth

API key via X-API-Key header

Versioning

Current version: v1

Authentication

Every request must include your API key in the X-API-Key request header. You can alternatively pass it as a query parameter ?api_key= for quick testing.

Keep your API key secret. Do not expose it in client-side code or public repositories. Contact us immediately if a key is compromised, we can disable it instantly.

bash

# Recommended: header
curl https://oceanbluecorp.com/api/v1/jobs \
  -H "X-API-Key: obk_live_your_api_key_here"

# Alternative: query param (testing only)
curl "https://oceanbluecorp.com/api/v1/jobs?api_key=obk_live_your_api_key_here"

Status	Code	Meaning
401	Missing API key	No X-API-Key header provided
401	Invalid API key	Key not found in our system
403	Key disabled	Key has been revoked or disabled
403	Missing scope	Key does not hold the scope this endpoint needs

Scopes

Each key is issued at one of two access levels. A read-only key that calls a write endpoint gets a 403 naming the scope it is missing, in a requiredScope field. Ask your Ocean Blue contact if you need a level changed; the key value itself does not change.

Access level	Scopes	Endpoints
View jobs	`jobs:read`	GET /api/v1/jobs, GET /api/v1/jobs/:id
Create and view jobs	`jobs:read, jobs:write`	All of the above, plus POST /api/v1/jobs

Endpoints

Postings created over the API arrive as draft unless you send status, so a recruiter reviews them before they reach the public careers site. Rates, client and vendor details and recruiter assignments cannot be set through this endpoint.

Filtering & Pagination

By default the list endpoint returns only active and open jobs. You can combine any query params.

bash

# Active contract jobs in Ohio, page 2
GET /api/v1/jobs?type=contract&status=active&page=2&limit=10

# All open jobs in "SAP Practice" department
GET /api/v1/jobs?department=SAP+Practice&status=open

# Specific job by ID
GET /api/v1/jobs/b3f1a2c4-1234-5678-abcd-ef0123456789

Field	Values
status	`active` · `open` · `paused` · `closed`
type	`full-time` · `part-time` · `contract` · `contract-to-hire` · `direct-hire` · `managed-teams` · `remote`
limit	Integer 1–100. Default 20.

Response Schema

All job objects returned by the API contain these fields. Internal fields (pay rates, recruiter details, billing data) are never included.

Field	Type	Notes
`id`	`string`	UUID, use this to fetch by /api/v1/jobs/:id
`postingId`	`string \| null`	Human-readable ID, e.g. OB-2025-0042
`title`	`string`	Job title
`department`	`string`	Business unit / practice area
`location`	`string`	City and state, e.g. Columbus, OH
`state`	`string \| null`	Two-letter state code
`type`	`string`	Employment type, see filtering table above
`description`	`string`	Full job description text
`requirements`	`string[]`	Array of requirement bullet points
`responsibilities`	`string[]`	Array of responsibility bullet points
`salary`	`object \| null`	{ min, max, currency } if disclosed
`status`	`string`	active \| open \| paused \| closed
`submissionDueDate`	`string \| null`	ISO 8601 application deadline
`clientName`	`string \| null`	End-client company name if disclosed
`vendorName`	`string \| null`	Staffing vendor name if applicable
`postedByName`	`string \| null`	Name of the recruiter who posted
`createdAt`	`string`	ISO 8601 creation timestamp
`updatedAt`	`string \| null`	ISO 8601 last-updated timestamp

Errors

All errors return a JSON body with an error field.

json

{
  "error": "Missing API key. Pass X-API-Key header."
}

HTTP Code	Meaning	Action
401	Missing or invalid API key	Check that X-API-Key is set and correct
403	API key disabled	Contact us, your key may have been revoked
404	Job not found	The job ID does not exist or was removed
500	Internal server error	Retry after a moment; contact us if persistent

Quickstart

Copy-paste examples to get up and running in minutes.

cURL

bash

curl https://oceanbluecorp.com/api/v1/jobs \
  -H "X-API-Key: obk_live_your_key_here" | jq .

JavaScript / TypeScript

typescript

const BASE = "https://oceanbluecorp.com/api/v1";
const KEY  = process.env.OCEAN_BLUE_API_KEY;

async function getJobs(page = 1) {
  const res = await fetch(`${BASE}/jobs?page=${page}&limit=20`, {
    headers: { "X-API-Key": KEY! },
  });
  if (!res.ok) throw new Error(`API error ${res.status}`);
  return res.json(); // { data: Job[], meta: { total, page, ... } }
}

async function getJob(id: string) {
  const res = await fetch(`${BASE}/jobs/${id}`, {
    headers: { "X-API-Key": KEY! },
  });
  if (!res.ok) throw new Error(`API error ${res.status}`);
  return res.json(); // { data: Job }
}

Python

python

import os, requests

BASE = "https://oceanbluecorp.com/api/v1"
HEADERS = {"X-API-Key": os.environ["OCEAN_BLUE_API_KEY"]}

def get_jobs(page=1, limit=20):
    r = requests.get(f"{BASE}/jobs", headers=HEADERS,
                     params={"page": page, "limit": limit})
    r.raise_for_status()
    return r.json()  # {"data": [...], "meta": {...}}

def get_job(job_id: str):
    r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS)
    r.raise_for_status()
    return r.json()  # {"data": {...}}

Get Access

Ready to integrate?

API access is available to vetted job platforms and technology partners. Reach out to our team and we'll issue you an API key within one business day.

Request API Access View Open Positions