{ "openapi": "3.0.4", "info": { "title": "Vollna API", "description": "API for managing Upwork profiles, proposals, results, and filters", "version": "1.0.0" }, "servers": [ { "url": "https://api.vollna.com/v1" } ], "tags": [ { "name": "Profiles", "description": "Manage Upwork profiles" }, { "name": "Proposals", "description": "Access and manage Upwork proposals" }, { "name": "Results", "description": "View monitoring results and projects" }, { "name": "Filters", "description": "Manage monitoring filters" }, { "name": "Auto Bidding", "description": "Manage auto bidding jobs and setups" } ], "paths": { "/profiles": { "get": { "tags": [ "Profiles" ], "summary": "List profiles", "description": "Returns a list of Upwork freelancers and agencies profiles accessible to the authenticated team", "parameters": [ { "name": "type", "in": "query", "description": "Filter profiles by type", "required": false, "schema": { "type": "string", "enum": [ "freelancer", "agency" ] } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "minimum": 10, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Profile" } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiToken": [] } ] } }, "/proposals": { "get": { "tags": [ "Proposals" ], "summary": "List proposals", "description": "Returns a list of proposals for a specific Upwork profile", "parameters": [ { "name": "profileId", "in": "query", "description": "Upwork profile ID (from `/profiles` API endpoint)", "required": true, "schema": { "type": "integer" } }, { "name": "organizationId", "in": "query", "description": "Organization ID (from `/organizations` API endpoint)", "deprecated": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "minimum": 10, "maximum": 100, "default": 20 } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "enum": [ "submittedAt" ], "default": "submittedAt" } }, { "name": "order", "in": "query", "description": "Sort order", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Proposal" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiToken": [] } ] } }, "/proposals/{id}": { "get": { "tags": [ "Proposals" ], "summary": "Get proposal by ID", "description": "Returns a single proposal by its numeric ID", "parameters": [ { "name": "id", "in": "path", "description": "Proposal ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Proposal" } } } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiToken": [] } ] } }, "/proposals/by-uid/{applicationUid}": { "get": { "tags": [ "Proposals" ], "summary": "Get proposal by application UID", "description": "Returns a single proposal by its Upwork application UID", "parameters": [ { "name": "applicationUid", "in": "path", "description": "Upwork application UID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Proposal" } } } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiToken": [] } ] } }, "/invitations": { "get": { "tags": [ "Invitations" ], "summary": "List invitations", "description": "Returns a list of invitations for a specific Upwork profile", "parameters": [ { "name": "profileId", "in": "query", "description": "Upwork profile ID (from `/profiles` API endpoint)", "required": true, "schema": { "type": "integer" } }, { "name": "organizationId", "in": "query", "description": "Organization ID (from `/organizations` API endpoint)", "deprecated": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "minimum": 10, "maximum": 100, "default": 20 } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "enum": [ "invitedAt" ], "default": "invitedAt" } }, { "name": "order", "in": "query", "description": "Sort order", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invitation" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiToken": [] } ] } }, "/filters": { "get": { "tags": [ "Filters" ], "summary": "List filters", "description": "Returns a list of monitoring filters accessible to the authenticated user", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" } } } } } } }, "400": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiToken": [] } ] } }, "/filters/{id}/results": { "get": { "tags": [ "Filters" ], "summary": "List results for a filter", "description": "Returns a list of monitoring results for a specific filter", "parameters": [ { "name": "id", "in": "path", "description": "Filter ID", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "minimum": 10, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringResult" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiToken": [] } ] } }, "/filters/{id}/projects": { "get": { "tags": [ "Projects" ], "summary": "List projects for a filter", "description": "Returns a list of projects matching a monitoring filter. Credits are consumed for projects that have not been accessed in the current billing period.", "parameters": [ { "name": "id", "in": "path", "description": "Filter ID", "required": true, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "minimum": 10, "maximum": 100, "default": 20 } }, { "name": "next_cursor", "in": "query", "description": "Cursor for pagination (timestamp)", "required": false, "schema": { "type": "integer" } }, { "name": "latest_published_ts", "in": "query", "description": "Latest published timestamp", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "is_last": { "type": "boolean" }, "next_cursor": { "type": "integer", "description": "Timestamp for next page cursor" }, "latest_published_ts": { "type": "integer", "description": "Timestamp of the latest published project" } } }, "credits": { "type": "object", "properties": { "remaining": { "type": "integer", "description": "Credits remaining in current billing period (-1 for unlimited)", "example": 9980 }, "reset_date": { "type": "string", "format": "date-time", "description": "When credits reset (ISO 8601)", "example": "2026-01-16T00:00:00+00:00" }, "new_projects_consumed": { "type": "integer", "description": "Number of new projects that consumed credits (0 if already viewed)", "example": 5 }, "total_projects_returned": { "type": "integer", "description": "Total projects returned", "example": 20 } } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required - Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Insufficient credits" }, "message": { "type": "string", "description": "Actionable detail. Requests are all-or-nothing, so a page wider than the remaining balance is refused without consuming anything.", "example": "This request needs 20 project credits and 8 remain. Lower the \"limit\" parameter to fit the remaining balance." }, "credits_needed": { "type": "integer", "description": "Credits the refused request would have consumed.", "example": 20 }, "credits_remaining": { "type": "integer", "example": 0 }, "credits_reset_date": { "type": "string", "format": "date-time", "example": "2026-01-16T00:00:00+00:00" } } } } } } }, "security": [ { "apiToken": [] } ] } }, "/results/{id}/projects": { "get": { "tags": [ "Projects" ], "summary": "List projects for a result", "description": "Returns a list of projects associated with a monitoring result. Credits are consumed for projects that have not been accessed in the current billing period.", "parameters": [ { "name": "id", "in": "path", "description": "Result ID", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "minimum": 10, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "credits": { "type": "object", "properties": { "remaining": { "type": "integer", "description": "Credits remaining in current billing period (-1 for unlimited)", "example": 9980 }, "reset_date": { "type": "string", "format": "date-time", "description": "When credits reset (ISO 8601)", "example": "2026-01-16T00:00:00+00:00" }, "new_projects_consumed": { "type": "integer", "description": "Number of new projects that consumed credits (0 if already viewed)", "example": 5 }, "total_projects_returned": { "type": "integer", "description": "Total projects returned", "example": 20 } } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required - Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Insufficient credits" }, "message": { "type": "string", "description": "Actionable detail. Requests are all-or-nothing, so a page wider than the remaining balance is refused without consuming anything.", "example": "This request needs 20 project credits and 8 remain. Lower the \"limit\" parameter to fit the remaining balance." }, "credits_needed": { "type": "integer", "description": "Credits the refused request would have consumed.", "example": 20 }, "credits_remaining": { "type": "integer", "example": 0 }, "credits_reset_date": { "type": "string", "format": "date-time", "example": "2026-01-16T00:00:00+00:00" } } } } } } }, "security": [ { "apiToken": [] } ] } }, "/projects/lookup": { "get": { "tags": [ "Projects" ], "summary": "Lookup project by ciphertext or UID", "description": "Returns a single project by its Upwork ciphertext (~123456) or UID. This endpoint consumes credits when returning a project that hasn't been accessed before in the current billing period.", "parameters": [ { "name": "ciphertext", "in": "query", "description": "Upwork job ciphertext (e.g., ~123456). Provide either ciphertext or uid, not both.", "required": false, "schema": { "type": "string", "pattern": "^~\\d+$", "example": "~0123456789" } }, { "name": "uid", "in": "query", "description": "Upwork job UID. Provide either ciphertext or uid, not both.", "required": false, "schema": { "type": "string", "example": "1234567890123456789" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Project" }, "credits": { "type": "object", "properties": { "remaining": { "type": "integer", "description": "Credits remaining in current billing period (-1 for unlimited)", "example": 9995 }, "reset_date": { "type": "string", "format": "date-time", "description": "When credits reset (ISO 8601)", "example": "2026-01-16T00:00:00+00:00" }, "new_projects_consumed": { "type": "integer", "description": "Number of new projects that consumed credits (0 if already viewed)", "example": 1 }, "total_projects_returned": { "type": "integer", "description": "Total projects returned", "example": 1 } } } } } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_params": { "summary": "Missing parameters", "value": { "error": "Missing required parameter: ciphertext or uid" } }, "both_params": { "summary": "Both parameters provided", "value": { "error": "Provide either ciphertext or uid, not both" } }, "invalid_format": { "summary": "Invalid ciphertext format", "value": { "error": "Invalid ciphertext format. Expected format: ~123456" } } } } } }, "402": { "description": "Payment required - Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Insufficient credits" }, "message": { "type": "string", "description": "Actionable detail. Requests are all-or-nothing, so a page wider than the remaining balance is refused without consuming anything.", "example": "This request needs 20 project credits and 8 remain. Lower the \"limit\" parameter to fit the remaining balance." }, "credits_needed": { "type": "integer", "description": "Credits the refused request would have consumed.", "example": 20 }, "credits_remaining": { "type": "integer", "example": 0 }, "credits_reset_date": { "type": "string", "format": "date-time", "example": "2026-01-16T00:00:00+00:00" } } } } } }, "403": { "description": "Forbidden - No active subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found - Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiToken": [] } ] } }, "/auto-bidding/jobs/create": { "post": { "tags": [ "Auto Bidding" ], "summary": "Create auto bidding job", "description": "Create a new auto bidding job for automated Upwork proposal submission", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["setup_id", "upwork_job_id"], "properties": { "setup_id": { "type": "integer", "description": "The ID of the auto bidding setup to use" }, "upwork_job_id": { "type": "string", "description": "The Upwork job ID (usually starts with ~)" }, "project_id": { "type": "integer", "description": "Vollna project ID. If not provided, system will search by upwork_job_id" }, "scheduled_at": { "type": "string", "format": "date-time", "description": "Datetime to schedule the job at. Must be in the future. Accepts ISO 8601 (e.g. `2026-04-29T11:28:03Z` or `2026-04-29T11:28:03+00:00`) and SQL-style (`Y-m-d H:i:s`). Honored exactly: bypasses fair-slot scheduling and the higher-priority blocking-job nudge. Correctness checks (location restrictions, daily/monthly/trial limits, duplicate detection) still apply and may mark the job as `skipped`. Takes precedence over `scheduled_in`." }, "scheduled_in": { "type": "integer", "minimum": 15, "maximum": 60, "default": 15, "description": "Minutes from now to schedule the job (15-60 range). Alternative to scheduled_at" }, "cover_letter": { "type": "string", "description": "Custom cover letter text. If not provided, uses setup's template" }, "answers": { "type": "array", "items": { "type": "object", "required": ["question", "answer"], "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } }, "description": "Array of question/answer pairs for job application questions" }, "bid_amount": { "type": "number", "format": "float", "minimum": 5.00, "maximum": 1000000.00, "description": "Bid amount for the job (hourly or fixed price)" }, "boost_bid_amount": { "type": "integer", "description": "Number of connects to boost the bid with" } } } } } }, "responses": { "201": { "description": "Job created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoBiddingJobResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Job already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } } }, "security": [ { "apiToken": [] } ] } }, "/auto-bidding/jobs/{id}/status": { "get": { "tags": [ "Auto Bidding" ], "summary": "Get job status", "description": "Retrieve the current status of an auto bidding job", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The job ID" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoBiddingJobStatusResponse" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiToken": [] } ] } }, "/auto-bidding/jobs/{id}/skip": { "post": { "tags": [ "Auto Bidding" ], "summary": "Skip job", "description": "Skip a scheduled auto bidding job", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The job ID" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional reason for skipping the job" } } } } } }, "responses": { "200": { "description": "Job skipped successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoBiddingJobSkipResponse" } } } }, "400": { "description": "Bad request - job cannot be skipped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiToken": [] } ] } }, "/auto-bidding/setups": { "get": { "tags": [ "Auto Bidding" ], "summary": "List auto bidding setups", "description": "Retrieve a list of auto bidding setups with optional status filtering", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "string", "enum": ["inactive", "active", "draft", "paused"] }, { "type": "integer", "enum": [0, 1, 2, 3] } ] }, "description": "Filter setups by status" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoBiddingSetupsResponse" } } } }, "400": { "description": "Invalid status value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiToken": [] } ] } }, "/auto-bidding/setups/{id}": { "get": { "tags": [ "Auto Bidding" ], "summary": "Get setup details", "description": "Retrieve detailed information about a specific auto bidding setup", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The setup ID" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoBiddingSetupResponse" } } } }, "404": { "description": "Setup not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiToken": [] } ] } }, "/auto-bidding/setups/{setupId}/jobs": { "get": { "tags": [ "Auto Bidding" ], "summary": "List setup jobs", "description": "Retrieve a list of jobs for a specific auto bidding setup with optional filters", "parameters": [ { "name": "setupId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The setup ID" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": ["pending", "processing", "completed", "failed", "skipped"] }, "description": "Filter jobs by status" }, { "name": "scheduled_only", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "If true, returns only future scheduled jobs" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 1000 }, "description": "Maximum number of results to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Offset for pagination" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoBiddingJobsResponse" } } } }, "404": { "description": "Setup not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiToken": [] } ] } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } } }, "Pagination": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of items", "example": 100 }, "page": { "type": "integer", "description": "Current page number", "example": 1 }, "limit": { "type": "integer", "description": "Number of items per page", "example": 20 }, "pages": { "type": "integer", "description": "Total number of pages", "example": 5 } } }, "CursorPagination": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "is_last": { "type": "boolean" }, "next_cursor": { "type": "string", "format": "date-time" }, "latest_published_ts": { "type": "string", "format": "date-time" } } }, "Profile": { "type": "object", "properties": { "id": { "type": "integer", "description": "Upwork profile ID", "example": 1 }, "label": { "type": "string", "description": "Upwork profile name", "example": "ACME, Inc." }, "type": { "type": "string", "enum": [ "freelancer", "agency" ], "description": "Upwork profile type", "example": "agency" }, "lastSyncAt": { "type": "string", "format": "date-time", "description": "Last sync date and time" }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Member ID", "example": 1 }, "fullName": { "type": "string", "description": "Member full name", "example": "John Doe" } } } }, "connectsBalance": { "type": "integer", "description": "Connects balance", "example": 123 } } }, "Proposal": { "type": "object", "properties": { "id": { "type": "integer", "description": "Proposal ID", "example": 1 }, "applicationUid": { "type": "string", "description": "Application UID", "example": "1234567890123456789" }, "submittedAt": { "type": "string", "format": "date-time", "description": "Submission date and time" }, "coverLetter": { "type": "string", "description": "Cover letter" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "description": "Client's question" }, "answer": { "type": "string", "description": "Your answer" } } } }, "jobDetails": { "type": "object", "properties": { "title": { "type": "string", "description": "Job title" }, "postedAt": { "type": "string", "format": "date-time", "description": "Job posted date and time" } } }, "freelancer": { "type": "object", "properties": { "id": { "type": "integer", "description": "Member ID", "example": 1 }, "fullName": { "type": "string", "description": "Member full name", "example": "John Doe" } } }, "businessManager": { "type": "object", "properties": { "id": { "type": "integer", "description": "Member ID", "example": 2 }, "fullName": { "type": "string", "description": "Member full name", "example": "Jane Doe" } } }, "upworkProfile": { "type": "object", "description": "Upwork profile details", "properties": { "id": { "type": "integer", "description": "Upwork profile ID", "example": 1 }, "label": { "type": "string", "description": "Upwork profile name", "example": "ACME, Inc." }, "type": { "type": "string", "enum": [ "freelancer", "agency" ], "description": "Upwork profile type", "example": "agency" } } }, "upworkOrganization": { "type": "object", "deprecated": true, "description": "Deprecated, use `upworkProfile` instead", "properties": { "id": { "type": "integer", "description": "Organization ID", "example": 1 }, "label": { "type": "string", "description": "Organization label", "example": "ACME, Inc." }, "type": { "type": "string", "enum": [ "freelancer", "agency" ], "description": "Organization type", "example": "agency" } } }, "connects": { "type": "integer", "description": "Connects spent", "example": 16 }, "boost": { "type": "integer", "description": "Boost", "example": 8 }, "terms": { "type": "object", "properties": { "fixedPrice": { "type": "number", "format": "float", "description": "Fixed price", "example": 1000 }, "hourlyRate": { "type": "number", "format": "float", "description": "Hourly rate", "example": 100 }, "increasePercent": { "type": "integer", "description": "Increase percent", "example": 10 }, "increaseFrequency": { "type": "integer", "description": "Increase frequency in months", "example": 3 } } }, "isViewed": { "type": "boolean" }, "isInterviewed": { "type": "boolean" }, "isHired": { "type": "boolean" }, "isWithdrawn": { "type": "boolean" }, "isInvitation": { "type": "boolean" }, "isArchived": { "type": "boolean" }, "occupationUid": { "type": "string" }, "occupationTitle": { "type": "string" }, "submissionPosition": { "type": "integer", "description": "Submission position", "example": 3 }, "boostOutbid": { "type": "boolean" }, "coverLetterVariant": { "type": "string" }, "biddingTemplate": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "project": { "$ref": "#/components/schemas/Project", "nullable": true, "description": "Linked project from Vollna database (if found via Elasticsearch)" } } }, "Invitation": { "type": "object", "properties": { "id": { "type": "integer", "description": "Invitation ID", "example": 13 }, "upworkProfile": { "type": "object", "description": "Upwork profile details", "properties": { "id": { "type": "integer", "description": "Upwork profile ID", "example": 1 }, "label": { "type": "string", "description": "Upwork profile name" }, "type": { "type": "string", "description": "Upwork profile type", "example": "freelancer" } } }, "upworkOrganization": { "type": "object", "deprecated": true, "description": "Deprecated, use `upworkProfile` instead", "properties": { "id": { "type": "integer", "description": "Organization ID", "example": 1 }, "label": { "type": "string", "description": "Organization name" }, "type": { "type": "string", "description": "Organization type", "example": "freelancer" } } }, "invitationUid": { "type": "string", "description": "Invitation UID from Upwork", "example": "1234567890" }, "title": { "type": "string", "description": "Job title", "example": "Symfony PHP Developer for Educational Application" }, "jobPostingUid": { "type": "string", "description": "Job posting UID from Upwork", "example": "1234567890" }, "invitationLetter": { "type": "string", "description": "Invitation letter content", "example": "Hello!\n\nI'd like to invite you to take a look at the job I've posted..." }, "clientUid": { "type": "string", "description": "Client UID from Upwork", "example": "1234567890" }, "contractor": { "type": "object", "description": "Contractor details", "properties": { "id": { "type": "integer", "description": "Contractor ID", "example": 1 }, "fullName": { "type": "string", "description": "Contractor full name", "example": "John Doe" } } }, "contractorUid": { "type": "string", "description": "Contractor UID from Upwork", "example": "1234567890" }, "invitedAt": { "type": "string", "format": "date-time", "description": "Invitation date and time", "example": "2022-08-01T20:04:53+00:00" }, "createdAt": { "type": "string", "format": "date-time", "description": "Record creation date and time", "example": "2025-05-17T13:30:44+00:00" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Record last update date and time", "example": "2025-05-17T13:30:44+00:00" }, "statusLabel": { "type": "string", "description": "Current status of the invitation", "example": "Job is closed" }, "project": { "$ref": "#/components/schemas/Project", "nullable": true, "description": "Linked project from Vollna database (if found via Elasticsearch)" } } }, "Project": { "type": "object", "properties": { "title": { "type": "string", "description": "Project title" }, "description": { "type": "string", "description": "Project description" }, "skills": { "type": "string", "description": "Required skills, comma-separated" }, "url": { "type": "string", "format": "uri", "description": "Project URL" }, "publishedAt": { "type": "string", "format": "date-time", "description": "When the project was published" }, "clientQuestions": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Questions from the client" }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Project categories" }, "site": { "type": "string", "description": "Source site (e.g. Upwork.com)" }, "budget": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Fixed price", "Hourly rate" ], "description": "Budget type" }, "amount": { "type": "string", "description": "Budget amount with currency symbol" } } }, "clientDetails": { "type": "object", "properties": { "paymentMethodVerified": { "type": "boolean", "description": "Whether client's payment method is verified" }, "country": { "type": "string", "description": "Client's country" }, "totalSpent": { "type": "number", "format": "float", "description": "Total amount spent by client", "example": 103580 }, "totalHires": { "type": "integer", "description": "Total number of hires by client", "example": 100 }, "hireRate": { "type": "number", "format": "float", "description": "Client's hire rate", "example": 0.5 }, "rating": { "type": "number", "format": "float", "description": "Client's rating", "example": 4.5 }, "reviews": { "type": "integer", "description": "Number of client reviews", "example": 78 } } }, "clientWorkHistory": { "type": "array", "nullable": true, "description": "Client's work history with previous freelancers", "items": { "type": "object", "properties": { "job_info": { "type": "object", "properties": { "uid": { "type": "string", "nullable": true, "description": "Job UID" }, "title": { "type": "string", "nullable": true, "description": "Job title" }, "type": { "type": "string", "nullable": true, "description": "Job type" } } }, "status": { "type": "string", "nullable": true, "description": "Job status (e.g., 'ACTIVE' for jobs in progress)" }, "start_date": { "type": "string", "nullable": true, "description": "Job start date" }, "end_date": { "type": "string", "nullable": true, "description": "Job end date" }, "total_hours": { "type": "number", "format": "float", "nullable": true, "description": "Total hours worked" }, "total_charge": { "type": "number", "format": "float", "nullable": true, "description": "Total amount charged" }, "feedback": { "type": "object", "nullable": true, "description": "Feedback from client to freelancer", "properties": { "score": { "type": "number", "format": "float", "nullable": true, "description": "Rating score" }, "comment": { "type": "string", "nullable": true, "description": "Feedback comment" } } }, "feedback_to_client": { "type": "object", "nullable": true, "description": "Feedback from freelancer to client", "properties": { "score": { "type": "number", "format": "float", "nullable": true, "description": "Rating score" }, "comment": { "type": "string", "nullable": true, "description": "Feedback comment" } } }, "rate": { "type": "object", "nullable": true, "description": "Rate information", "properties": { "amount": { "type": "number", "format": "float", "nullable": true, "description": "Rate amount" } } } } } } } }, "Filter": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "MonitoringResult": { "type": "object", "properties": { "id": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "totalProjects": { "type": "integer", "description": "Total number of projects in this monitoring result" } } }, "ConflictError": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" }, "job_id": { "type": "integer" } } }, "AutoBiddingJobResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "job": { "$ref": "#/components/schemas/AutoBiddingJob" } } }, "AutoBiddingJobStatusResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "job": { "$ref": "#/components/schemas/AutoBiddingJobStatus" } } }, "AutoBiddingJobSkipResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "job": { "$ref": "#/components/schemas/AutoBiddingJobSkipped" } } }, "AutoBiddingSetupsResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "count": { "type": "integer" }, "setups": { "type": "array", "items": { "$ref": "#/components/schemas/AutoBiddingSetup" } } } }, "AutoBiddingSetupResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "setup": { "$ref": "#/components/schemas/AutoBiddingSetupDetailed" } } }, "AutoBiddingJobsResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "setup_id": { "type": "integer" }, "setup_name": { "type": "string" }, "total_count": { "type": "integer" }, "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/AutoBiddingJobDetailed" } } } }, "AutoBiddingJob": { "type": "object", "properties": { "id": { "type": "integer" }, "upwork_job_id": { "type": "string" }, "status": { "type": "string" }, "scheduled_at": { "type": "string" }, "setup_id": { "type": "integer" }, "setup_name": { "type": "string" }, "project_id": { "type": "integer", "nullable": true }, "cover_letter_length": { "type": "integer" }, "answers_count": { "type": "integer" }, "bid_amount": { "type": "string", "nullable": true } } }, "AutoBiddingJobStatus": { "type": "object", "properties": { "id": { "type": "integer" }, "upwork_job_id": { "type": "string" }, "status": { "type": "string", "description": "Available values: `scheduled`, `processing`, `applied`, `skipped`, `failed`" }, "reason": { "type": "string", "nullable": true, "description": "Reason for the job status (skip reason or error message), available only for `skipped` and `failed` statuses" }, "status_title": { "type": "string", "description": "Human-readable status title" }, "scheduled_at": { "type": "string" }, "processed_at": { "type": "string", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "retry_count": { "type": "integer" }, "is_ready_for_processing": { "type": "boolean" }, "upwork_proposal_id": { "type": "integer", "nullable": true, "deprecated": true, "description": "Proposal ID (deprecated, use `proposal_id` instead)" }, "proposal_id": { "type": "integer", "nullable": true, "description": "Proposal ID" }, "upwork_application_uid": { "type": "string", "nullable": true, "description": "Upwork application UID of the proposal" } } }, "AutoBiddingJobSkipped": { "type": "object", "properties": { "id": { "type": "integer" }, "upwork_job_id": { "type": "string" }, "status": { "type": "string" }, "status_title": { "type": "string" }, "skip_initiator": { "type": "string" }, "skip_reason": { "type": "string", "nullable": true }, "processed_at": { "type": "string" }, "setup_id": { "type": "integer" }, "setup_name": { "type": "string" } } }, "AutoBiddingSetup": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "integer" }, "status_name": { "type": "string" }, "filter": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true }, "name": { "type": "string", "nullable": true } } }, "bidding_template": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true }, "name": { "type": "string", "nullable": true } } }, "schedule": { "type": "string" }, "schedule_label": { "type": "string" }, "timezone": { "type": "string" }, "bidding_delay_minutes": { "type": "integer" }, "daily_proposals_limit": { "type": "integer" }, "total_proposals_sent": { "type": "integer" }, "proposals_sent_today": { "type": "integer" }, "last_run_at": { "type": "string", "nullable": true }, "last_proposal_date": { "type": "string", "nullable": true }, "business_manager_id": { "type": "string", "nullable": true }, "subscription_id": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "nullable": true } } }, "AutoBiddingSetupDetailed": { "allOf": [ { "$ref": "#/components/schemas/AutoBiddingSetup" }, { "type": "object", "properties": { "bidding_template": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true }, "name": { "type": "string", "nullable": true }, "hourly_rate": { "type": "number", "nullable": true }, "templates": { "type": "array", "items": { "type": "string" }, "nullable": true } } }, "custom_schedule": { "type": "object", "nullable": true } } } ] }, "AutoBiddingJobDetailed": { "type": "object", "properties": { "id": { "type": "integer" }, "upwork_job_id": { "type": "string" }, "project_id": { "type": "integer", "nullable": true }, "status": { "type": "string" }, "status_title": { "type": "string" }, "scheduled_at": { "type": "string", "nullable": true }, "processed_at": { "type": "string", "nullable": true }, "cover_letter_length": { "type": "integer" }, "has_answers": { "type": "boolean" }, "answers_count": { "type": "integer" }, "bid_amount": { "type": "string", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "retry_count": { "type": "integer" }, "last_retry_at": { "type": "string", "nullable": true }, "skip_reason": { "type": "string", "nullable": true }, "is_ready_for_processing": { "type": "boolean" }, "upwork_proposal_id": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "nullable": true } } } }, "securitySchemes": { "apiToken": { "type": "apiKey", "name": "X-API-TOKEN", "in": "header", "description": "API token for authentication" } } } }