{ "openapi": "3.1.0", "info": { "title": "TAP Recruiter Customer API", "version": "1.0.0", "description": "Agency Growth owner API. Server-to-server HTTPS only. Keys have explicit scopes and an expiry; 60 requests/minute per agency. Candidate data and file transfer are not exposed by v1.", "contact": { "url": "https://taprecruiter.com/contact" } }, "servers": [ { "url": "https://taprecruiter.com/api/v1" } ], "security": [ { "BearerKey": [] } ], "paths": { "/clients": { "get": { "summary": "List owned client companies (clients:read)", "operationId": "listClients", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "after", "in": "query", "schema": { "type": "string", "maxLength": 150 } } ], "responses": { "200": { "description": "Client company names and IDs; no individual contact details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Client" } }, "revision": { "type": "integer" }, "requestId": { "type": "string" }, "nextCursor": { "type": [ "string", "null" ] }, "replayed": { "type": "boolean" } } } } } }, "400": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/jobs": { "get": { "summary": "List agency-owned jobs (jobs:read)", "operationId": "listJobs", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "after", "in": "query", "schema": { "type": "string", "maxLength": 150 } } ], "responses": { "200": { "description": "Owned jobs in ID order, with pagination cursor.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "revision": { "type": "integer" }, "requestId": { "type": "string" }, "nextCursor": { "type": [ "string", "null" ] }, "replayed": { "type": "boolean" } } } } } }, "400": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a private job (jobs:write)", "operationId": "createJob", "description": "Does not advertise or share the job. Retry using the same Idempotency-Key. Replays return the current representation of the original job.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,100}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJob" } } } }, "responses": { "200": { "description": "Job details. ETag contains the current workspace revision.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Job" }, "revision": { "type": "integer" }, "requestId": { "type": "string" }, "nextCursor": { "type": [ "string", "null" ] }, "replayed": { "type": "boolean" } } } } } }, "201": { "description": "Job details. ETag contains the current workspace revision.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Job" }, "revision": { "type": "integer" }, "requestId": { "type": "string" }, "nextCursor": { "type": [ "string", "null" ] }, "replayed": { "type": "boolean" } } } } } }, "400": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/jobs/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,150}$" } } ], "get": { "summary": "Read job and revision (jobs:read)", "operationId": "getJob", "responses": { "200": { "description": "Job details. ETag contains the current workspace revision.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Job" }, "revision": { "type": "integer" }, "requestId": { "type": "string" }, "nextCursor": { "type": [ "string", "null" ] }, "replayed": { "type": "boolean" } } } } } }, "400": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update job text (jobs:write)", "operationId": "updateJob", "description": "Only title, location and description. Existing pricing, sharing and status are preserved. Use the ETag from the latest GET; concurrent workspace changes return 409.", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[0-9]+\"$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "title": { "type": "string", "maxLength": 150 }, "location": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 30000 } } } } } }, "responses": { "200": { "description": "Job details. ETag contains the current workspace revision.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Job" }, "revision": { "type": "integer" }, "requestId": { "type": "string" }, "nextCursor": { "type": [ "string", "null" ] }, "replayed": { "type": "boolean" } } } } } }, "400": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/jobs/{id}/progress": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,150}$" } } ], "get": { "summary": "Read aggregate job progress (jobs:read)", "operationId": "jobProgress", "responses": { "200": { "description": "Counts by application stage, with no candidate identities.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "jobId": { "type": "string", "maxLength": 150 }, "status": { "type": "string", "maxLength": 150 }, "stages": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } } }, "revision": { "type": "integer" }, "requestId": { "type": "string" }, "nextCursor": { "type": [ "string", "null" ] }, "replayed": { "type": "boolean" } } } } } }, "400": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected; inspect error.code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "BearerKey": { "type": "http", "scheme": "bearer", "bearerFormat": "tap_live__" } }, "schemas": { "CreateJob": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "maxLength": 150 }, "clientId": { "type": "string", "maxLength": 150 }, "location": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 30000 }, "type": { "enum": [ "Permanent", "Contract", "Labour hire" ] }, "salary": { "type": "number", "minimum": 0, "maximum": 10000000 }, "currency": { "enum": [ "AUD", "USD", "GBP", "EUR", "NZD", "SGD", "CAD", "INR", "PHP" ] }, "taxTreatment": { "enum": [ "exclusive", "gst-exclusive", "vat-exclusive", "no-tax", "custom" ] }, "taxNotes": { "type": "string", "maxLength": 500 }, "feeModel": { "enum": [ "Percentage", "Fixed fee", "Hourly rate", "Daily rate" ] }, "feeValue": { "type": "number", "minimum": 0, "maximum": 10000000 } }, "required": [ "title", "clientId", "location", "type", "salary", "currency", "taxTreatment", "feeModel", "feeValue" ] }, "Job": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 150 }, "clientId": { "type": "string", "maxLength": 150 }, "location": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 30000 }, "type": { "enum": [ "Permanent", "Contract", "Labour hire" ] }, "salary": { "type": "number", "minimum": 0, "maximum": 10000000 }, "currency": { "enum": [ "AUD", "USD", "GBP", "EUR", "NZD", "SGD", "CAD", "INR", "PHP" ] }, "taxTreatment": { "enum": [ "exclusive", "gst-exclusive", "vat-exclusive", "no-tax", "custom" ] }, "taxNotes": { "type": "string", "maxLength": 500 }, "feeModel": { "enum": [ "Percentage", "Fixed fee", "Hourly rate", "Daily rate" ] }, "feeValue": { "type": "number", "minimum": 0, "maximum": 10000000 }, "id": { "type": "string", "maxLength": 150 }, "status": { "enum": [ "Open", "On hold", "Closed" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "Client": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 150 }, "name": { "type": "string", "maxLength": 150 }, "industry": { "type": "string", "maxLength": 150 }, "location": { "type": "string", "maxLength": 150 }, "status": { "type": "string", "maxLength": 150 } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string" } } } } } }