{ "openapi": "3.1.0", "info": { "title": "Getmany Service API", "description": "This is the reference documentation and schemas for the Getmany Service API.", "version": "1.0.0" }, "servers": [ { "url": "https://api.getmany.io/service", "description": "Production" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": {} }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Agency", "description": "Agency information tied to the workspace, including agency profile details, seat-holders in an agency, and aggregated proposal performance stats" }, { "name": "Job Searches", "description": "Saved search configurations that scan the Upwork market" }, { "name": "Jobs Feed", "description": "Endpoints related to retrieving the jobs list matching with a job search configuration" }, { "name": "Bid Intents", "description": "List and manage bidding intents" }, { "name": "Miscellaneous", "description": "Various general purpose endpoints" }, { "name": "Master Inbox", "description": "Chat room management and messaging endpoints" } ], "paths": { "/v1/agency": { "get": { "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uid": { "type": "string", "description": "Stable unique identifier of the agency.", "example": "23b1f7fa-a3bc-41dd-9b89-301d8d9c8d50" }, "name": { "type": "string", "description": "Public display name of the agency.", "example": "PixelPioneers Studio" }, "description": { "type": "string", "description": "Plain-text overview shown on the Upwork agency profile." }, "timezone": { "type": "string", "description": "IANA time-zone identifier of the agency\u2019s primary location (e.g. `Europe/Kyiv`).", "example": "Europe/Kyiv" }, "connectsBalance": { "type": "number", "description": "Remaining Connects tokens the agency can spend on proposals.", "example": 324 } }, "required": [ "uid", "name", "description", "timezone", "connectsBalance" ] } } } } } }, "404": { "description": "Agency not found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" }, "instance": { "type": "string", "format": "uri" } }, "required": ["type", "title", "status", "detail", "instance"] } } } } }, "operationId": "getV1Agency", "tags": ["Agency"], "parameters": [], "summary": "Retrieve agency profile", "description": "Returns the complete profile of the single agency linked to the authenticated workspace." } }, "/v1/agency/members": { "get": { "responses": { "200": { "description": "Members list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uid": { "type": "string", "description": "Stable unique identifier of the member.", "example": "6cf9a849-ff9d-487e-8440-d5dff574b4e2" }, "ciphertext": { "type": "string", "description": "Opaque, base64-encoded string used for secure member metadata (exact format is internal)." }, "name": { "type": "string", "description": "First-name + surname of the person.", "example": "Oksana Moroz" }, "role": { "type": "string", "enum": ["member", "business_manager"], "description": "`member` = regular contractor, `business_manager` = can manage billing and proposals." }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code of the member\u2019s registered location.", "example": "UA" }, "certificates": { "type": "array", "items": { "type": "string" }, "description": "List of Upwork skill certificates the member holds (slugs).", "example": ["seo_cert", "gads_cert"] }, "generalProfile": { "type": "object", "properties": { "title": { "type": "string", "description": "Profile headline (max 70 chars recommended by Upwork).", "example": "Full-stack JS / TS Engineer" }, "description": { "type": "string", "description": "Profile overview in Markdown or plain text." }, "hourlyRate": { "type": "number", "description": "Displayed hourly rate in USD.", "example": 65 }, "skills": { "type": "array", "items": { "type": "string" }, "description": "Top-level skill slugs chosen from Upwork taxonomy.", "example": ["reactjs", "node.js", "postgresql"] } }, "required": [ "title", "description", "hourlyRate", "skills" ], "description": "Mandatory \u201cgeneral\u201d profile shown to all clients." }, "specializedProfiles": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Specialized profile headline." }, "description": { "type": "string", "description": "Overview focused on the specialization." }, "hourlyRate": { "type": "number", "description": "Specialized profile rate in USD (can differ from general)." }, "skills": { "type": "array", "items": { "type": "string" }, "description": "Skills relevant to this specialization." } }, "required": [ "title", "description", "hourlyRate", "skills" ] }, "description": "Optional specialized profiles that highlight distinct niches.\n\n*An empty array means no specialized profiles configured*." } }, "required": [ "uid", "ciphertext", "name", "role", "countryCode", "certificates", "generalProfile", "specializedProfiles" ] } } } } } } } }, "operationId": "getV1AgencyMembers", "tags": ["Agency"], "parameters": [ { "in": "query", "name": "pageCursor", "schema": { "type": "string" } }, { "in": "query", "name": "pageSize", "schema": { "type": "string" } }, { "in": "query", "name": "role", "schema": { "type": "string", "enum": ["member", "business_manager"] } } ], "summary": "List agency members", "description": "Retrieves agency members. Supports optional `role` filter and cursor pagination." } }, "/v1/agency/stats": { "get": { "responses": { "200": { "description": "Stats object", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sent": { "type": "number", "description": "Total proposals submitted.", "example": 150 }, "viewed": { "type": "number", "description": "Proposals the client opened in Upwork UI.", "example": 42 }, "accepted": { "type": "number", "description": "Proposals that moved to an \u201cInterview\u201d state.", "example": 18 }, "hired": { "type": "number", "description": "Proposals that resulted in a contract.", "example": 7 }, "conversionRate": { "type": "number", "description": "Optional percentage `(hired \u00f7 sent) \u00d7 100`. Left undefined when `sent` is 0.", "example": 4.67 } }, "required": ["sent", "viewed", "accepted", "hired"], "description": "Counts of proposals at each lifecycle stage." } } } } } } }, "operationId": "getV1AgencyStats", "tags": ["Agency"], "parameters": [ { "in": "query", "name": "from", "schema": { "type": "string", "format": "date-time" }, "required": true }, { "in": "query", "name": "to", "schema": { "type": "string", "format": "date-time" }, "required": true }, { "in": "query", "name": "include", "schema": { "type": "string", "const": "conversion_rate" }, "required": false } ], "summary": "Retrieve performance metrics", "description": "Aggregated proposal stats for a given date range." } }, "/v1/agency/proposals": { "get": { "responses": { "200": { "description": "Proposals list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "proposal": { "type": "object", "properties": { "uid": { "type": "string", "description": "Unique identifier of the proposal", "example": "1955676881223622657" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) when the proposal was created/sent.", "example": "2025-08-13T17:04:38.077Z" }, "status": { "type": "string", "enum": ["SUBMITTED", "ACTIVE", "ARCHIVED"], "description": "Current lifecycle state of the proposal: `SUBMITTED` = sent to the client, `ACTIVE` = client has opened it, `ARCHIVED` = proposal is no longer active." }, "results": { "type": "array", "items": { "type": "object", "properties": { "timeStamp": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) when the event occurred." }, "type": { "type": "string", "description": "Event type (e.g. SENT, VIEWED_BY_CLIENT, CLIENT_REPLIED, HIRED, CLOSED, DECLINED_BY_CLIENT, WITHDRAWN).", "example": "VIEWED_BY_CLIENT" } }, "required": ["timeStamp", "type"] }, "description": "Chronological list of lifecycle events recorded for the proposal." }, "isBoosted": { "type": "boolean", "description": "Whether the proposal was submitted with a Boost (paid promotion).", "example": false }, "isBoostOutbid": { "type": "boolean", "description": "Whether the proposal\u2019s Boost has been outbid by another freelancer.", "example": false }, "boostedConnects": { "type": ["number", "null"], "description": "Number of Connects used for boosting the proposal. Null if the proposal was not boosted.", "example": 10 }, "coverLetter": { "type": "string", "description": "Text of the cover letter sent with the proposal." }, "connectsSpent": { "type": "number", "description": "Number of Upwork Connects spent on this proposal.", "example": 20 }, "questions": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "description": "Text of the screening question from the client." }, "answer": { "type": "string", "description": "Text of the answer provided by the freelancer." } }, "required": ["question", "answer"] }, "description": "List of screening questions and answers included in the proposal." }, "applicationTimeSeconds": { "type": ["number", "null"], "description": "Time in seconds between the job being published and the proposal being sent. Null if the job publish time is unknown.", "example": 312.5 }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "List of attachment URLs submitted with the proposal.", "example": [] }, "bidDecisionResult": { "type": ["object", "null"], "properties": { "shouldApply": { "type": "boolean", "description": "Whether the AI bidder decided to apply to the job.", "example": true }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Reasons behind the AI bid decision." }, "prompt": { "type": "string", "description": "Prompt used by the AI bidder for the decision." } }, "required": [ "shouldApply", "reasons", "prompt" ], "description": "Result of the AI bid decision for this proposal. Null when not applicable." }, "hubspot": { "type": ["object", "null"], "properties": { "contactId": { "type": ["string", "null"], "description": "HubSpot contact ID linked to the proposal." }, "dealId": { "type": ["string", "null"], "description": "HubSpot deal ID linked to the proposal." }, "leadId": { "type": ["string", "null"], "description": "HubSpot lead ID linked to the proposal." } }, "required": ["contactId", "dealId", "leadId"], "description": "HubSpot CRM entities linked to the proposal. Null if no HubSpot integration data exists." }, "pipedrive": { "type": ["object", "null"], "properties": { "contactId": { "type": ["number", "null"], "description": "Pipedrive contact ID linked to the proposal." }, "leadId": { "type": ["string", "null"], "description": "Pipedrive lead ID linked to the proposal." }, "dealId": { "type": ["number", "null"], "description": "Pipedrive deal ID linked to the proposal." } }, "required": ["contactId", "leadId", "dealId"], "description": "Pipedrive CRM entities linked to the proposal. Null if no Pipedrive integration data exists." }, "chatRoomId": { "type": "string", "description": "Upwork chat room ID associated with the proposal, if a conversation exists." } }, "description": "Proposal payload and related metadata." }, "freelancer": { "type": "object", "properties": { "uid": { "type": "string", "description": "Stable unique identifier of the freelancer.", "example": "669484786717323264" }, "name": { "type": "string", "description": "Display name of the freelancer.", "example": "John Doe" } }, "description": "Freelancer who authored the proposal." }, "manager": { "type": "object", "properties": { "uid": { "type": "string", "description": "Stable unique identifier of the agency member who sent it.", "example": "1747622284724662272" }, "name": { "type": "string", "description": "Display name of the agency member (manager).", "example": "Jane Doe" } }, "description": "Agency member associated with the proposal." }, "job": { "type": "object", "properties": { "uid": { "type": "string", "description": "Unique identifier of the job posting on Upwork.", "example": "1955676437925687781" }, "title": { "type": "string", "description": "Job title as shown on Upwork.", "example": "AWS Lambda Function for Integration with SQS and Bubble.io" }, "description": { "type": "string", "description": "Full job description text." }, "url": { "type": "string", "format": "uri", "description": "Canonical URL of the job posting.", "example": "https://www.upwork.com/jobs/~021955676437925687781" }, "cipherText": { "type": "string", "description": "Upwork cipher text identifier of the job posting.", "example": "~021955676437925687781" }, "duration": { "type": "string", "description": "Client-stated expected duration.", "example": "Up to 1 month" }, "price": { "type": "number", "description": "Budget amount for fixed-price jobs.", "example": 1000 }, "minHourlyRate": { "type": ["number", "null"], "description": "Minimum hourly rate if the job is hourly; null for fixed-price jobs.", "example": null }, "maxHourlyRate": { "type": ["number", "null"], "description": "Maximum hourly rate if the job is hourly; null for fixed-price jobs.", "example": null }, "hireType": { "type": "string", "description": "Hiring arrangement value as provided by the source system.", "example": "ANY" }, "budgetType": { "type": "string", "description": "Budget type value as provided by the source system.", "example": "FIXED" }, "prefEnglishSkills": { "type": "string", "description": "Client\u2019s preferred English proficiency level.", "example": "ANY" }, "projectType": { "type": "string", "description": "Project type label.", "example": "One-time project" }, "skills": { "type": "array", "items": { "type": "string" }, "description": "List of required or relevant skills for the job.", "example": [ "API", "AWS Lambda", "Python", "API Integration", "Amazon Web Services" ] }, "vendorExpLevel": { "type": "string", "description": "Requested experience level.", "example": "EXPERT" }, "vendorCountries": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Country codes the client wants the vendor to be located in. Null if unrestricted.", "example": ["US", "GB"] }, "category": { "type": "string", "description": "Top-level job category.", "example": "Web Development" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) when the job was created.", "example": "2025-08-13T17:02:52.446Z" }, "publishedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) when the job was published.", "example": "2025-08-13T17:02:52.446Z" }, "isFeatured": { "type": "boolean", "description": "Whether the job is featured.", "example": false }, "jobScore": { "type": "number", "description": "Getmany internal job score.", "example": 4 } }, "description": "Job posting details." }, "client": { "type": "object", "properties": { "uid": { "type": ["string", "null"], "description": "Unique identifier of the client company.", "example": "1234567890" }, "country": { "type": "string", "description": "Client country code (as provided by the source system).", "example": "US" }, "city": { "type": ["string", "null"], "description": "Client city. Null if unknown.", "example": "San Francisco" }, "companySize": { "type": ["number", "null"], "description": "Client company size. Null if unknown.", "example": 50 }, "avgHourlyRate": { "type": "number", "description": "Client\u2019s historical average hourly rate paid.", "example": 15.001127904353712 }, "totalSpent": { "type": "number", "description": "Total lifetime spend by the client on the platform.", "example": 4717.25 }, "industry": { "type": "string", "description": "Client\u2019s industry segment.", "example": "Art & Design" }, "timezone": { "type": "string", "description": "Client\u2019s IANA time zone.", "example": "America/Sao_Paulo" }, "connectedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) when the client account was connected/created.", "example": "2020-10-17T00:00:00.000Z" }, "totalHires": { "type": "number", "description": "Total number of hires made by the client.", "example": 3 }, "feedbackCount": { "type": "number", "description": "Number of feedback entries associated with the client.", "example": 6 }, "feedbackScore": { "type": "number", "description": "Average feedback score associated with the client.", "example": 5 }, "hireRate": { "type": "number", "description": "Client hire rate (percentage value).", "example": 60 }, "isEnterprise": { "type": "boolean", "description": "Whether the client is flagged as an enterprise account.", "example": false }, "isPaymentMethodVerified": { "type": "boolean", "description": "Whether the client\u2019s payment method is verified.", "example": true }, "isPhoneNumberVerified": { "type": "boolean", "description": "Whether the client\u2019s phone number is verified.", "example": false } }, "description": "Client/account metadata for the job." }, "jobSearch": { "type": ["object", "null"], "properties": { "id": { "type": "string", "description": "ID of the job search entry in Getmany.", "example": "689b6e81d6d44dcb40b9a9cf" }, "url": { "type": "string", "format": "uri", "description": "Deep link to the job search entry in Getmany.", "example": "https://app.getmany.io/jse/689b6e81d6d44dcb40b9a9cf" }, "name": { "type": "string", "description": "Name of the job search in Getmany.", "example": "My Upwork Search" } }, "description": "Metadata of related resources in Getmany. Null when the proposal was not sent via Getmany." }, "invitation": { "type": ["object", "null"], "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) when the client invitation for the same job was received by the agency.", "example": "2025-08-13T17:04:38.077Z" } }, "required": ["createdAt"], "description": "Client invitation associated with this proposal, matched by job and agency. Null when the proposal was not sent in response to an invitation." } } } }, "meta": { "type": "object", "properties": { "pageSize": { "type": "number", "description": "Number of proposals requested per page.", "example": 10 }, "nextCursor": { "type": ["string", "null"], "description": "Cursor to pass as `pageCursor` to fetch the next page. Null when there are no more results.", "example": "66b2f1c4e2a1b30012a4d9f1" }, "total": { "type": "number", "description": "Total number of proposals matching the query.", "example": 124 } }, "description": "Pagination metadata." } } } } } } }, "operationId": "getV1AgencyProposals", "tags": ["Agency"], "parameters": [ { "in": "query", "name": "pageCursor", "schema": { "type": "string" } }, { "in": "query", "name": "pageSize", "schema": { "type": "string" } }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": ["active", "submitted", "archived"] } } ], "summary": "List agency proposals", "description": "Retrieves agency proposals. Supports optional `status` filter and cursor pagination." } }, "/v1/agency/proposals/{id}": { "get": { "responses": { "200": { "description": "Proposal details object", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "proposal": { "type": "object", "properties": { "uid": { "type": "string", "description": "Unique identifier of the proposal", "example": "1955676881223622657" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) when the proposal was created/sent.", "example": "2025-08-13T17:04:38.077Z" }, "status": { "type": "string", "enum": ["SUBMITTED", "ACTIVE", "ARCHIVED"], "description": "Current lifecycle state of the proposal: `SUBMITTED` = sent to the client, `ACTIVE` = client has opened it, `ARCHIVED` = proposal is no longer active." }, "results": { "type": "array", "items": { "type": "object", "properties": { "timeStamp": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) when the event occurred." }, "type": { "type": "string", "description": "Event type (e.g. SENT, VIEWED_BY_CLIENT, CLIENT_REPLIED, HIRED, CLOSED, DECLINED_BY_CLIENT, WITHDRAWN).", "example": "VIEWED_BY_CLIENT" } }, "required": ["timeStamp", "type"] }, "description": "Chronological list of lifecycle events recorded for the proposal." }, "isBoosted": { "type": "boolean", "description": "Whether the proposal was submitted with a Boost (paid promotion).", "example": false }, "isBoostOutbid": { "type": "boolean", "description": "Whether the proposal\u2019s Boost has been outbid by another freelancer.", "example": false }, "boostedConnects": { "type": ["number", "null"], "description": "Number of Connects used for boosting the proposal. Null if the proposal was not boosted.", "example": 10 }, "coverLetter": { "type": "string", "description": "Text of the cover letter sent with the proposal." }, "connectsSpent": { "type": "number", "description": "Number of Upwork Connects spent on this proposal.", "example": 20 }, "questions": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "description": "Text of the screening question from the client." }, "answer": { "type": "string", "description": "Text of the answer provided by the freelancer." } }, "required": ["question", "answer"] }, "description": "List of screening questions and answers included in the proposal." }, "applicationTimeSeconds": { "type": ["number", "null"], "description": "Time in seconds between the job being published and the proposal being sent. Null if the job publish time is unknown.", "example": 312.5 }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "List of attachment URLs submitted with the proposal.", "example": [] }, "bidDecisionResult": { "type": ["object", "null"], "properties": { "shouldApply": { "type": "boolean", "description": "Whether the AI bidder decided to apply to the job.", "example": true }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Reasons behind the AI bid decision." }, "prompt": { "type": "string", "description": "Prompt used by the AI bidder for the decision." } }, "required": ["shouldApply", "reasons", "prompt"], "description": "Result of the AI bid decision for this proposal. Null when not applicable." }, "hubspot": { "type": ["object", "null"], "properties": { "contactId": { "type": ["string", "null"], "description": "HubSpot contact ID linked to the proposal." }, "dealId": { "type": ["string", "null"], "description": "HubSpot deal ID linked to the proposal." }, "leadId": { "type": ["string", "null"], "description": "HubSpot lead ID linked to the proposal." } }, "required": ["contactId", "dealId", "leadId"], "description": "HubSpot CRM entities linked to the proposal. Null if no HubSpot integration data exists." }, "pipedrive": { "type": ["object", "null"], "properties": { "contactId": { "type": ["number", "null"], "description": "Pipedrive contact ID linked to the proposal." }, "leadId": { "type": ["string", "null"], "description": "Pipedrive lead ID linked to the proposal." }, "dealId": { "type": ["number", "null"], "description": "Pipedrive deal ID linked to the proposal." } }, "required": ["contactId", "leadId", "dealId"], "description": "Pipedrive CRM entities linked to the proposal. Null if no Pipedrive integration data exists." }, "chatRoomId": { "type": "string", "description": "Upwork chat room ID associated with the proposal, if a conversation exists." } }, "description": "Proposal payload and related metadata." }, "freelancer": { "type": "object", "properties": { "uid": { "type": "string", "description": "Stable unique identifier of the freelancer.", "example": "669484786717323264" }, "name": { "type": "string", "description": "Display name of the freelancer.", "example": "John Doe" } }, "description": "Freelancer who authored the proposal." }, "manager": { "type": "object", "properties": { "uid": { "type": "string", "description": "Stable unique identifier of the agency member who sent it.", "example": "1747622284724662272" }, "name": { "type": "string", "description": "Display name of the agency member (manager).", "example": "Jane Doe" } }, "description": "Agency member associated with the proposal." }, "job": { "type": "object", "properties": { "uid": { "type": "string", "description": "Unique identifier of the job posting on Upwork.", "example": "1955676437925687781" }, "title": { "type": "string", "description": "Job title as shown on Upwork.", "example": "AWS Lambda Function for Integration with SQS and Bubble.io" }, "description": { "type": "string", "description": "Full job description text." }, "url": { "type": "string", "format": "uri", "description": "Canonical URL of the job posting.", "example": "https://www.upwork.com/jobs/~021955676437925687781" }, "cipherText": { "type": "string", "description": "Upwork cipher text identifier of the job posting.", "example": "~021955676437925687781" }, "duration": { "type": "string", "description": "Client-stated expected duration.", "example": "Up to 1 month" }, "price": { "type": "number", "description": "Budget amount for fixed-price jobs.", "example": 1000 }, "minHourlyRate": { "type": ["number", "null"], "description": "Minimum hourly rate if the job is hourly; null for fixed-price jobs.", "example": null }, "maxHourlyRate": { "type": ["number", "null"], "description": "Maximum hourly rate if the job is hourly; null for fixed-price jobs.", "example": null }, "hireType": { "type": "string", "description": "Hiring arrangement value as provided by the source system.", "example": "ANY" }, "budgetType": { "type": "string", "description": "Budget type value as provided by the source system.", "example": "FIXED" }, "prefEnglishSkills": { "type": "string", "description": "Client\u2019s preferred English proficiency level.", "example": "ANY" }, "projectType": { "type": "string", "description": "Project type label.", "example": "One-time project" }, "skills": { "type": "array", "items": { "type": "string" }, "description": "List of required or relevant skills for the job.", "example": [ "API", "AWS Lambda", "Python", "API Integration", "Amazon Web Services" ] }, "vendorExpLevel": { "type": "string", "description": "Requested experience level.", "example": "EXPERT" }, "vendorCountries": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Country codes the client wants the vendor to be located in. Null if unrestricted.", "example": ["US", "GB"] }, "category": { "type": "string", "description": "Top-level job category.", "example": "Web Development" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) when the job was created.", "example": "2025-08-13T17:02:52.446Z" }, "publishedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) when the job was published.", "example": "2025-08-13T17:02:52.446Z" }, "isFeatured": { "type": "boolean", "description": "Whether the job is featured.", "example": false }, "jobScore": { "type": "number", "description": "Getmany internal job score.", "example": 4 } }, "description": "Job posting details." }, "client": { "type": "object", "properties": { "uid": { "type": ["string", "null"], "description": "Unique identifier of the client company.", "example": "1234567890" }, "country": { "type": "string", "description": "Client country code (as provided by the source system).", "example": "US" }, "city": { "type": ["string", "null"], "description": "Client city. Null if unknown.", "example": "San Francisco" }, "companySize": { "type": ["number", "null"], "description": "Client company size. Null if unknown.", "example": 50 }, "avgHourlyRate": { "type": "number", "description": "Client\u2019s historical average hourly rate paid.", "example": 15.001127904353712 }, "totalSpent": { "type": "number", "description": "Total lifetime spend by the client on the platform.", "example": 4717.25 }, "industry": { "type": "string", "description": "Client\u2019s industry segment.", "example": "Art & Design" }, "timezone": { "type": "string", "description": "Client\u2019s IANA time zone.", "example": "America/Sao_Paulo" }, "connectedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) when the client account was connected/created.", "example": "2020-10-17T00:00:00.000Z" }, "totalHires": { "type": "number", "description": "Total number of hires made by the client.", "example": 3 }, "feedbackCount": { "type": "number", "description": "Number of feedback entries associated with the client.", "example": 6 }, "feedbackScore": { "type": "number", "description": "Average feedback score associated with the client.", "example": 5 }, "hireRate": { "type": "number", "description": "Client hire rate (percentage value).", "example": 60 }, "isEnterprise": { "type": "boolean", "description": "Whether the client is flagged as an enterprise account.", "example": false }, "isPaymentMethodVerified": { "type": "boolean", "description": "Whether the client\u2019s payment method is verified.", "example": true }, "isPhoneNumberVerified": { "type": "boolean", "description": "Whether the client\u2019s phone number is verified.", "example": false } }, "description": "Client/account metadata for the job." }, "jobSearch": { "type": ["object", "null"], "properties": { "id": { "type": "string", "description": "ID of the job search entry in Getmany.", "example": "689b6e81d6d44dcb40b9a9cf" }, "url": { "type": "string", "format": "uri", "description": "Deep link to the job search entry in Getmany.", "example": "https://app.getmany.io/jse/689b6e81d6d44dcb40b9a9cf" }, "name": { "type": "string", "description": "Name of the job search in Getmany.", "example": "My Upwork Search" } }, "description": "Metadata of related resources in Getmany. Null when the proposal was not sent via Getmany." }, "invitation": { "type": ["object", "null"], "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) when the client invitation for the same job was received by the agency.", "example": "2025-08-13T17:04:38.077Z" } }, "required": ["createdAt"], "description": "Client invitation associated with this proposal, matched by job and agency. Null when the proposal was not sent in response to an invitation." } } } } } } } } }, "operationId": "getV1AgencyProposalsById", "tags": ["Agency"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "summary": "Fetch agency proposal by ID", "description": "Retrieves agency proposal." } }, "/v1/agency/invitations": { "get": { "responses": { "200": { "description": "Invitations list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "invite": { "type": "object", "properties": { "uid": { "type": "string", "description": "Unique identifier of the invitation", "example": "1955676881223622657" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) when the invitation was received.", "example": "2025-08-13T17:04:38.077Z" }, "status": { "type": "string", "enum": ["PENDING", "DECLINED", "ACCEPTED"], "description": "Current status of the invitation: `PENDING` = awaiting response, `DECLINED` = freelancer declined, `ACCEPTED` = freelancer accepted." }, "result": { "type": "string", "enum": [ "DECLINED", "CLOSED", "WITHDRAWN", "REMOVED", "PENDING", "EXPIRED" ], "description": "Outcome of the invitation: `PENDING` = still active, `DECLINED` = declined by freelancer, `CLOSED` = job closed, `WITHDRAWN` = client withdrew, `REMOVED` = job removed, `EXPIRED` = invitation expired." }, "letter": { "type": "string", "description": "Invitation message from the client." }, "title": { "type": "string", "description": "Title of the invitation or job.", "example": "AWS Lambda Function for Integration with SQS and Bubble.io" } }, "description": "Invitation payload and related metadata." }, "freelancer": { "type": "object", "properties": { "uid": { "type": "string", "description": "Stable unique identifier of the freelancer.", "example": "669484786717323264" }, "name": { "type": "string", "description": "Display name of the freelancer.", "example": "John Doe" }, "photoUrl": { "type": "string", "format": "uri", "description": "URL of the freelancer's profile photo.", "example": "https://www.upwork.com/profile-portraits/c15X4ONdSkuDWnML5uiYN1ymYBayBtQDwy3t3BvL1P-4cHCYK37N9-JnoLk7L98ja1" } }, "description": "Freelancer who received the invitation." }, "job": { "type": "object", "properties": { "uid": { "type": "string", "description": "Unique identifier of the job posting on Upwork.", "example": "1955676437925687781" }, "title": { "type": "string", "description": "Job title as shown on Upwork.", "example": "AWS Lambda Function for Integration with SQS and Bubble.io" }, "description": { "type": "string", "description": "Full job description text." }, "url": { "type": "string", "format": "uri", "description": "Canonical URL of the job posting.", "example": "https://www.upwork.com/jobs/~021955676437925687781" } }, "description": "Job posting details." }, "client": { "type": "object", "properties": { "country": { "type": "string", "description": "Client country code (as provided by the source system).", "example": "US" }, "totalSpent": { "type": "number", "description": "Total lifetime spend by the client on the platform.", "example": 4717.25 }, "timezone": { "type": "string", "description": "Client's IANA time zone.", "example": "America/Sao_Paulo" } }, "description": "Client/account metadata for the job." } }, "required": ["invite", "freelancer", "job", "client"] } } } } } } } }, "operationId": "getV1AgencyInvitations", "tags": ["Agency"], "parameters": [ { "in": "query", "name": "pageCursor", "schema": { "type": "string" } }, { "in": "query", "name": "pageSize", "schema": { "type": "string" } }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": ["accepted", "pending", "declined"] } } ], "summary": "List agency invitations", "description": "Retrieves agency invitations. Supports optional `status` filter and cursor pagination." } }, "/v1/agency/{id}": { "get": { "responses": { "200": { "description": "Agency public info", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the agency", "example": "1621294330163461120" }, "name": { "type": "string", "description": "Public display name of the agency.", "example": "PixelPioneers Studio" }, "title": { "type": "string", "description": "Agency title or tagline", "example": "Top-rated web and mobile development agency" }, "description": { "type": "string", "description": "Plain-text overview shown on the Upwork agency profile." }, "photo": { "type": ["string", "null"], "format": "uri", "description": "URL of the agency\u2019s profile photo.", "example": "https://assets.static-upwork.com/org-logo/1621293360163461120" }, "city": { "type": ["string", "null"], "description": "City of the agency\u2019s primary location.", "example": "Kyiv" }, "country": { "type": ["string", "null"], "description": "Country code of the agency\u2019s primary location.", "example": "Ukraine" }, "clientFocus": { "type": "array", "items": { "type": "string" }, "description": "List of client focus areas.", "example": [ "LARGE_BUSINESS", "MEDIUM_BUSINESS", "VERY_SMALL_BUSINESS", "SMALL_BUSINESS" ] }, "minRate": { "type": ["string", "null"], "description": "Minimum hourly rate (USD) among all agency members.", "example": "25" }, "maxRate": { "type": ["string", "null"], "description": "Maximum hourly rate (USD) among all agency members.", "example": "150" }, "minimumProjectSize": { "type": ["string", "null"], "description": "Minimum project size (USD) among all agency members.", "example": "$5,000+" }, "totalJobs": { "type": "string", "description": "Total number of jobs completed by the agency.", "example": "128" }, "memberSinceDateTime": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) when the agency joined Upwork.", "example": "2021-05-17T00:00:00.000Z" }, "numberOfEmployees": { "type": ["string", "null"], "description": "Number of employees in the agency.", "example": "11-50" }, "cipherText": { "type": "string", "description": "Opaque, base64-encoded string used for secure member metadata (exact format is internal).", "example": "~0111406dc44d63b0f3" }, "skills": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the skill", "example": "158" }, "preferredLabel": { "type": "string", "description": "Human-readable name of the skill", "example": "Web Development" } }, "required": ["id", "preferredLabel"] }, "description": "List of top skills associated with the agency." }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the service", "example": "1621294430163461120" }, "occupationId": { "type": "string", "description": "Identifier of the occupation/category", "example": "531770282589057037" }, "occupationName": { "type": "string", "description": "Name of the occupation/category", "example": "Web, Mobile & Software Dev" }, "description": { "type": ["string", "null"], "description": "Service description text", "example": "Full-stack web and mobile development services" }, "portfolioItemId": { "type": ["string", "null"], "description": "Identifier of a portfolio item illustrating this service", "example": "1621294430163461120" }, "customTitle": { "type": ["string", "null"], "description": "Custom title for the service", "example": "Full-stack web and mobile development" }, "serviceOrder": { "type": "number", "description": "Relative order of the service in the list", "example": 1 } }, "required": [ "id", "occupationId", "occupationName", "description", "portfolioItemId", "customTitle", "serviceOrder" ] }, "description": "List of services offered by the agency." }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the project", "example": "1621294530163461120" }, "title": { "type": "string", "description": "Project title", "example": "E-commerce Website for Retail Client" }, "thumbnail": { "type": ["string", "null"], "format": "uri", "description": "URL of the project thumbnail image", "example": "http://localhost:3010/att/download/portfolio/agencies/uid/1621294860163461120/profile/projects/files/afb7b939-e5dc-4176-b439-5bb00d7d12a5" }, "description": { "type": "string", "description": "Project description text" }, "completionDateTime": { "type": ["string", "null"], "format": "date-time", "description": "ISO-8601 timestamp (UTC) when the project was completed", "example": "2023-11-15T00:00:00.000Z" }, "projectUrl": { "type": ["string", "null"], "format": "uri", "description": "URL of the project (if available)", "example": "https://www.example.com/projects/ecommerce-website" }, "categoryId": { "type": "string", "description": "Identifier of the project category", "example": "531770282589057037" } }, "required": [ "id", "title", "thumbnail", "description", "completionDateTime", "projectUrl", "categoryId" ] }, "description": "List of recent projects completed by the agency." }, "upworkHistory": { "type": "object", "properties": { "upworkHistoryList": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": ["Active", "Closed"], "description": "Status of the contract", "example": "Active" }, "title": { "type": "string", "description": "Title of the contract", "example": "Website Development Project" }, "startedOnDateTime": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) when the contract started", "example": "2023-01-10T00:00:00.000Z" }, "endedOnDateTime": { "type": ["string", "null"], "format": "date-time", "description": "ISO-8601 timestamp (UTC) when the contract ended", "example": "2023-06-15T00:00:00.000Z" }, "totalHours": { "type": "number", "description": "Total hours logged on the contract", "example": 150 }, "hourlyRate": { "type": ["number", "null"], "description": "Hourly rate in USD (if applicable)", "example": 50 }, "totalCost": { "type": "number", "description": "Total cost of the contract in USD", "example": 7500 }, "totalCharges": { "type": "number", "description": "Total charges including fees in USD", "example": 8250 }, "contractorEarnings": { "type": "number", "description": "Earnings of the contractor in USD", "example": 7500 }, "feedback": { "type": ["object", "null"], "properties": { "comment": { "type": ["string", "null"], "description": "Feedback comment left by the client", "example": "Great work, very professional!" }, "score": { "type": ["number", "null"], "description": "Feedback score (1-5)", "example": 5 } }, "required": ["comment", "score"], "description": "Feedback details (if feedback was left)" } }, "required": [ "status", "title", "startedOnDateTime", "endedOnDateTime", "totalHours", "hourlyRate", "totalCost", "totalCharges", "contractorEarnings", "feedback" ] }, "description": "List of contracts and work history on Upwork." } }, "required": ["upworkHistoryList"], "description": "Upwork work history details." }, "locations": { "type": "array", "items": { "type": "object", "properties": { "city": { "type": ["string", "null"], "description": "City of the agency location.", "example": "New York City" }, "state": { "type": ["string", "null"], "description": "State or region of the agency location.", "example": "NY" }, "country": { "type": "string", "description": "Country of the agency location.", "example": "United States" }, "address": { "type": ["string", "null"], "description": "Street address of the agency location.", "example": "123 Main St, Suite 400" }, "zipCode": { "type": ["string", "null"], "description": "ZIP or postal code of the agency location.", "example": "01001" }, "id": { "type": "string", "description": "Unique identifier of the location.", "example": "1621294630163461120" } }, "required": [ "city", "state", "country", "address", "zipCode", "id" ], "description": "List of physical locations associated with the agency." }, "description": "Physical locations associated with the agency." }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the agency member.", "example": "1747622284724662272" }, "agencyOwner": { "type": "boolean", "description": "Whether the member is the agency owner.", "example": false }, "memberType": { "type": "string", "enum": ["MANAGER", "CONTRACTOR"], "description": "Type of member.", "example": "MANAGER" }, "vetter": { "type": ["boolean", "null"], "description": "Whether the member is a vetted freelancer.", "example": true }, "personalData": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the member\u2019s personal profile.", "example": "669484786717323264" }, "name": { "type": "string", "description": "Display name of the member.", "example": "John Doe" }, "portrait": { "type": "string", "format": "uri", "description": "URL of the member\u2019s profile portrait image.", "example": "https://www.upwork.com/profile-portraits/c15X4ONdSkuDWnML5uiYN1ymYBayBtQDwy3t3BvL1P-4cHCYK37N9-JnoLk7L98ja1" }, "ciphertext": { "type": "string", "description": "Opaque, base64-encoded string used for secure member metadata (exact format is internal).", "example": "~0111406dc44d63b0f3" }, "topRatedStatus": { "type": ["string", "null"], "description": "Top Rated status of the member.", "example": "top_rated" }, "topRatedPlusStatus": { "type": ["string", "null"], "description": "Top Rated Plus status of the member.", "example": "top_rated_plus" }, "jobSuccessScore": { "type": "number", "description": "Job Success Score percentage of the member.", "example": 96 }, "suspended": { "type": "boolean", "description": "Whether the member\u2019s profile is suspended.", "example": false }, "disabled": { "type": "boolean", "description": "Whether the member\u2019s profile is disabled.", "example": false } }, "required": [ "id", "name", "portrait", "ciphertext", "topRatedStatus", "topRatedPlusStatus", "jobSuccessScore", "suspended", "disabled" ], "description": "Personal data of the agency member." } }, "required": [ "id", "agencyOwner", "memberType", "vetter", "personalData" ] }, "description": "List of members associated with the agency." } }, "required": [ "id", "name", "title", "description", "photo", "city", "country", "clientFocus", "minRate", "maxRate", "minimumProjectSize", "totalJobs", "memberSinceDateTime", "numberOfEmployees", "cipherText", "skills", "services", "projects", "upworkHistory", "locations", "members" ] } } } } } } } }, "operationId": "getV1AgencyById", "tags": ["Agency"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "summary": "Get agency public info", "description": "Fetches the public profile information of an agency by its ID." } }, "/v1/job-searches": { "get": { "responses": { "200": { "description": "Search list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the job-search configuration", "example": "507f1f77bcf86cd799439011" }, "name": { "type": "string", "description": "Human-readable name of the job-search configuration", "example": "Mobile Dev \u2013 Long-term" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) of the last modification", "example": "2025-06-30T14:21:08Z" }, "bidder": { "type": "object", "properties": { "status": { "type": "string", "enum": ["not_configured", "active", "stopped"], "description": "Lifecycle state of the auto-bidder: `not_configured` \u2192 user has not provided settings; `active` \u2192 bidding is running; `stopped` \u2192 user paused bidding." }, "mode": { "type": ["string", "null"], "enum": ["template", "ai", null], "description": "Proposal composer engine. `template` = static template, `ai` = AI-generated. `null` when bidder is not configured." } }, "required": ["status", "mode"], "description": "Automated bidder configuration; omit or leave `null` to disable bidding." }, "searchConfig": { "type": "object", "properties": { "jobCategories": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "1.1", "1.2", "1.3", "1.4", "1.5", "1.6", "1.7", "2.1", "2.2", "2.3", "2.4", "2.5", "3.1", "3.2", "3.3", "4.1", "4.2", "4.3", "4.4", "4.5", "5.1", "5.2", "5.3", "5.4", "5.5", "5.6", "5.7", "5.8", "5.9", "5.10", "6.1", "6.2", "6.3", "6.4", "6.5", "6.6", "6.7", "6.8", "6.9", "6.10", "7.1", "7.2", "7.3", "7.4", "7.5", "7.6", "8.1", "8.2", "8.3", "8.4", "8.5", "9.1", "9.2", "9.3", "9.4", "10.1", "10.2", "10.3", "11.1", "11.2", "11.3", "11.4", "11.5", "11.6", "11.7", "11.8", "11.9", "11.10", "11.11", "11.12", "11.13", "12.1", "12.2", "12.3", "12.4", "12.5" ] }, "description": "Upwork category codes to include (e.g. `11.11` for \u201cMobile Development\u201d)." }, "excludeKeywords": { "type": ["object", "null"], "properties": { "active": { "type": "boolean", "description": "Indicates whether keywords are used to narrow the search" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "The list of keywords to search" }, "matchDescription": { "type": "boolean", "description": "Whether to match specified keywords against job descriptions" }, "matchSkills": { "type": "boolean", "description": "Whether to match specified keywords against job skills" }, "matchTitle": { "type": "boolean", "description": "Whether to match specified keywords against job titles" } }, "required": [ "active", "keywords", "matchDescription", "matchSkills", "matchTitle" ], "description": "Keywords that **must not** appear in title or description." }, "includeKeywords": { "type": ["object", "null"], "properties": { "active": { "type": "boolean", "description": "Indicates whether keywords are used to narrow the search" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "The list of keywords to search" }, "matchDescription": { "type": "boolean", "description": "Whether to match specified keywords against job descriptions" }, "matchSkills": { "type": "boolean", "description": "Whether to match specified keywords against job skills" }, "matchTitle": { "type": "boolean", "description": "Whether to match specified keywords against job titles" } }, "required": [ "active", "keywords", "matchDescription", "matchSkills", "matchTitle" ], "description": "Keywords that **must** appear in title or description." }, "budget": { "type": ["object", "null"], "properties": { "allowUnspecifiedBudget": { "type": ["boolean", "null"], "description": "Include job posts with no stated budget when `true`." }, "avgHourlyRate": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of a client\u2019s *average* hourly spend (USD)." }, "hourlyRate": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of the job\u2019s listed hourly rate (USD)." }, "connectsPrice": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of Connects required to bid." }, "fixedPrice": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of fixed-price budgets (USD)." }, "jobDurations": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "UNSPECIFIED", "UP_TO_ONE_MONTH", "UP_TO_THREE_MONTHS", "UP_TO_SIX_MONTHS", "MORE_THAN_SIX_MONTHS" ] }, "description": "Allowed contract durations." }, "hourlyWorkloads": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "UNSPECIFIED", "LESS_THAN_30_HOURS", "MORE_THAN_30_HOURS" ] }, "description": "Allowed weekly workloads." }, "noAvgHourlyRatePaid": { "type": ["boolean", "null"], "description": "Accept clients with no recorded average hourly rate." }, "noHireRate": { "type": ["boolean", "null"], "description": "Accept clients with zero hire rate." }, "onlyContractToHire": { "type": ["boolean", "null"], "description": "Limit to \u201cContract-to-hire\u201d postings." }, "minClientHireRate": { "type": ["number", "null"], "description": "Minimum client hire rate (%) required.", "example": 60 } }, "description": "Budget-related filters; `null` disables budget filtering." }, "client": { "type": ["object", "null"], "properties": { "companySizeRange": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "UNSPECIFIED", "SOLO_ENTERPRENEUR", "UP_TO_10_EMPLOYEES", "UP_TO_100_EMPOLOYEES", "UP_TO_500_EMPLOYEES", "UP_TO_1K_EMPLOYEES", "MORE_THAN_1K_EMPLOYEES" ] }, "description": "Allowed client company-size buckets." }, "descriptionLanguage": { "type": ["object", "null"], "properties": { "exclude": { "type": ["array", "null"], "items": { "type": "string" }, "description": "ISO-639-2 codes to exclude (e.g. `fra`)." }, "include": { "type": ["array", "null"], "items": { "type": "string" }, "description": "ISO-639-2 codes that must be present." } }, "description": "Language filters applied to job descriptions." }, "hireHistory": { "type": ["array", "null"], "items": { "type": "string", "enum": ["NONE", "UP_TO", "MORE_THAN"] }, "description": "Allowed buckets of previous hires made by the client." }, "includeLocations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COUNTRY", "SUBREGION", "REGION" ], "description": "Geographic granularity of the filter." }, "value": { "type": "string", "description": "Stable unique identifier." } }, "required": ["type", "value"] }, "description": "Locations filter" }, "excludeLocations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COUNTRY", "SUBREGION", "REGION" ], "description": "Geographic granularity of the filter." }, "value": { "type": "string", "description": "Stable unique identifier." } }, "required": ["type", "value"] }, "description": "Locations filter" }, "includeIndustry": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Industries that **must** match (by code or name)." }, "excludeIndustry": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Industries to exclude (by code or name)." }, "includeWithNoFeedback": { "type": ["boolean", "null"], "description": "Accept clients that have never received feedback." }, "totalSpent": { "type": ["object", "null", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Upper bound on client total spend (USD).", "example": { "min": 500, "max": null } }, "minFeedbackScore": { "type": ["number", "null"], "description": "Minimum average client feedback (0\u20135).", "example": 4.5 }, "paymentMethodVerified": { "type": ["boolean", "null"], "description": "Require the client\u2019s payment method to be verified." }, "phoneNumberVerified": { "type": ["boolean", "null"], "description": "Require the client\u2019s phone number to be verified." }, "timezones": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Allowed IANA time-zone identifiers.", "example": [ "America/New_York", "Europe/London" ] } }, "description": "Client-side filters; `null` disables them." }, "vendor": { "type": ["object", "null"], "properties": { "type": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "UNSPECIFIED", "FREELANCER", "AGENCY" ] }, "description": "Allowed vendor contract types (e.g. `AGENCY`)." }, "languages": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Required vendor language codes (ISO-639-1)." }, "englishProficiency": { "type": ["string", "null"], "enum": [ "BASIC", "CONVERSATIONAL", "FLUENT", "NATIVE", null ], "description": "Minimum English proficiency level required." }, "experienceLevel": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "BEGINNER", "INTERMEDIATE", "EXPERT" ] }, "description": "Allowed Upwork experience levels." }, "minGetmanyJobScore": { "type": ["number", "null"], "minimum": 0, "maximum": 5, "description": "Minimum Getmany Job Score (0-5) required", "example": 4.7 }, "includeLocations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COUNTRY", "SUBREGION", "REGION" ], "description": "Geographic granularity of the filter." }, "value": { "type": "string", "description": "Stable unique identifier." } }, "required": ["type", "value"] }, "description": "Locations filter" }, "includeFeatured": { "type": ["boolean", "null"], "description": "Limit to \u201cFeatured\u201d job posts." }, "includeWithoutCountryPreference": { "type": ["boolean", "null"], "description": "Include posts with no vendor location preference." }, "excludeWithQuestions": { "type": ["boolean", "null"], "description": "Exclude posts that contain screening questions." } }, "description": "Vendor-side (freelancer) filters; `null` disables them." } }, "description": "Grouping of all job-search filter parameters." } }, "required": [ "id", "name", "updatedAt", "bidder", "searchConfig" ] } } } } } } } }, "operationId": "getV1Job-searches", "tags": ["Job Searches"], "parameters": [ { "in": "query", "name": "pageCursor", "schema": { "type": "string" } }, { "in": "query", "name": "pageSize", "schema": { "type": "string" } } ], "summary": "List job searches", "description": "Lists all job-search configurations for the workspace." }, "post": { "responses": { "201": { "description": "Created", "headers": { "Location": { "description": "Canonical URI of the new job search", "schema": { "type": "string", "format": "uri" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the job-search configuration", "example": "507f1f77bcf86cd799439011" }, "name": { "type": "string", "description": "Human-readable name of the job-search configuration", "example": "Mobile Dev \u2013 Long-term" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) of the last modification", "example": "2025-06-30T14:21:08Z" }, "bidder": { "type": "object", "properties": { "status": { "type": "string", "enum": ["not_configured", "active", "stopped"], "description": "Lifecycle state of the auto-bidder: `not_configured` \u2192 user has not provided settings; `active` \u2192 bidding is running; `stopped` \u2192 user paused bidding." }, "mode": { "type": ["string", "null"], "enum": ["template", "ai", null], "description": "Proposal composer engine. `template` = static template, `ai` = AI-generated. `null` when bidder is not configured." } }, "required": ["status", "mode"], "description": "Automated bidder configuration; omit or leave `null` to disable bidding." }, "searchConfig": { "type": "object", "properties": { "jobCategories": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "1.1", "1.2", "1.3", "1.4", "1.5", "1.6", "1.7", "2.1", "2.2", "2.3", "2.4", "2.5", "3.1", "3.2", "3.3", "4.1", "4.2", "4.3", "4.4", "4.5", "5.1", "5.2", "5.3", "5.4", "5.5", "5.6", "5.7", "5.8", "5.9", "5.10", "6.1", "6.2", "6.3", "6.4", "6.5", "6.6", "6.7", "6.8", "6.9", "6.10", "7.1", "7.2", "7.3", "7.4", "7.5", "7.6", "8.1", "8.2", "8.3", "8.4", "8.5", "9.1", "9.2", "9.3", "9.4", "10.1", "10.2", "10.3", "11.1", "11.2", "11.3", "11.4", "11.5", "11.6", "11.7", "11.8", "11.9", "11.10", "11.11", "11.12", "11.13", "12.1", "12.2", "12.3", "12.4", "12.5" ] }, "description": "Upwork category codes to include (e.g. `11.11` for \u201cMobile Development\u201d)." }, "excludeKeywords": { "type": ["object", "null"], "properties": { "active": { "type": "boolean", "description": "Indicates whether keywords are used to narrow the search" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "The list of keywords to search" }, "matchDescription": { "type": "boolean", "description": "Whether to match specified keywords against job descriptions" }, "matchSkills": { "type": "boolean", "description": "Whether to match specified keywords against job skills" }, "matchTitle": { "type": "boolean", "description": "Whether to match specified keywords against job titles" } }, "required": [ "active", "keywords", "matchDescription", "matchSkills", "matchTitle" ], "description": "Keywords that **must not** appear in title or description." }, "includeKeywords": { "type": ["object", "null"], "properties": { "active": { "type": "boolean", "description": "Indicates whether keywords are used to narrow the search" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "The list of keywords to search" }, "matchDescription": { "type": "boolean", "description": "Whether to match specified keywords against job descriptions" }, "matchSkills": { "type": "boolean", "description": "Whether to match specified keywords against job skills" }, "matchTitle": { "type": "boolean", "description": "Whether to match specified keywords against job titles" } }, "required": [ "active", "keywords", "matchDescription", "matchSkills", "matchTitle" ], "description": "Keywords that **must** appear in title or description." }, "budget": { "type": ["object", "null"], "properties": { "allowUnspecifiedBudget": { "type": ["boolean", "null"], "description": "Include job posts with no stated budget when `true`." }, "avgHourlyRate": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of a client\u2019s *average* hourly spend (USD)." }, "hourlyRate": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of the job\u2019s listed hourly rate (USD)." }, "connectsPrice": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of Connects required to bid." }, "fixedPrice": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of fixed-price budgets (USD)." }, "jobDurations": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "UNSPECIFIED", "UP_TO_ONE_MONTH", "UP_TO_THREE_MONTHS", "UP_TO_SIX_MONTHS", "MORE_THAN_SIX_MONTHS" ] }, "description": "Allowed contract durations." }, "hourlyWorkloads": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "UNSPECIFIED", "LESS_THAN_30_HOURS", "MORE_THAN_30_HOURS" ] }, "description": "Allowed weekly workloads." }, "noAvgHourlyRatePaid": { "type": ["boolean", "null"], "description": "Accept clients with no recorded average hourly rate." }, "noHireRate": { "type": ["boolean", "null"], "description": "Accept clients with zero hire rate." }, "onlyContractToHire": { "type": ["boolean", "null"], "description": "Limit to \u201cContract-to-hire\u201d postings." }, "minClientHireRate": { "type": ["number", "null"], "description": "Minimum client hire rate (%) required.", "example": 60 } }, "description": "Budget-related filters; `null` disables budget filtering." }, "client": { "type": ["object", "null"], "properties": { "companySizeRange": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "UNSPECIFIED", "SOLO_ENTERPRENEUR", "UP_TO_10_EMPLOYEES", "UP_TO_100_EMPOLOYEES", "UP_TO_500_EMPLOYEES", "UP_TO_1K_EMPLOYEES", "MORE_THAN_1K_EMPLOYEES" ] }, "description": "Allowed client company-size buckets." }, "descriptionLanguage": { "type": ["object", "null"], "properties": { "exclude": { "type": ["array", "null"], "items": { "type": "string" }, "description": "ISO-639-2 codes to exclude (e.g. `fra`)." }, "include": { "type": ["array", "null"], "items": { "type": "string" }, "description": "ISO-639-2 codes that must be present." } }, "description": "Language filters applied to job descriptions." }, "hireHistory": { "type": ["array", "null"], "items": { "type": "string", "enum": ["NONE", "UP_TO", "MORE_THAN"] }, "description": "Allowed buckets of previous hires made by the client." }, "includeLocations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COUNTRY", "SUBREGION", "REGION" ], "description": "Geographic granularity of the filter." }, "value": { "type": "string", "description": "Stable unique identifier." } }, "required": ["type", "value"] }, "description": "Locations filter" }, "excludeLocations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COUNTRY", "SUBREGION", "REGION" ], "description": "Geographic granularity of the filter." }, "value": { "type": "string", "description": "Stable unique identifier." } }, "required": ["type", "value"] }, "description": "Locations filter" }, "includeIndustry": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Industries that **must** match (by code or name)." }, "excludeIndustry": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Industries to exclude (by code or name)." }, "includeWithNoFeedback": { "type": ["boolean", "null"], "description": "Accept clients that have never received feedback." }, "totalSpent": { "type": ["object", "null", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Upper bound on client total spend (USD).", "example": { "min": 500, "max": null } }, "minFeedbackScore": { "type": ["number", "null"], "description": "Minimum average client feedback (0\u20135).", "example": 4.5 }, "paymentMethodVerified": { "type": ["boolean", "null"], "description": "Require the client\u2019s payment method to be verified." }, "phoneNumberVerified": { "type": ["boolean", "null"], "description": "Require the client\u2019s phone number to be verified." }, "timezones": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Allowed IANA time-zone identifiers.", "example": [ "America/New_York", "Europe/London" ] } }, "description": "Client-side filters; `null` disables them." }, "vendor": { "type": ["object", "null"], "properties": { "type": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "UNSPECIFIED", "FREELANCER", "AGENCY" ] }, "description": "Allowed vendor contract types (e.g. `AGENCY`)." }, "languages": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Required vendor language codes (ISO-639-1)." }, "englishProficiency": { "type": ["string", "null"], "enum": [ "BASIC", "CONVERSATIONAL", "FLUENT", "NATIVE", null ], "description": "Minimum English proficiency level required." }, "experienceLevel": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "BEGINNER", "INTERMEDIATE", "EXPERT" ] }, "description": "Allowed Upwork experience levels." }, "minGetmanyJobScore": { "type": ["number", "null"], "minimum": 0, "maximum": 5, "description": "Minimum Getmany Job Score (0-5) required", "example": 4.7 }, "includeLocations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COUNTRY", "SUBREGION", "REGION" ], "description": "Geographic granularity of the filter." }, "value": { "type": "string", "description": "Stable unique identifier." } }, "required": ["type", "value"] }, "description": "Locations filter" }, "includeFeatured": { "type": ["boolean", "null"], "description": "Limit to \u201cFeatured\u201d job posts." }, "includeWithoutCountryPreference": { "type": ["boolean", "null"], "description": "Include posts with no vendor location preference." }, "excludeWithQuestions": { "type": ["boolean", "null"], "description": "Exclude posts that contain screening questions." } }, "description": "Vendor-side (freelancer) filters; `null` disables them." } }, "description": "Grouping of all job-search filter parameters." } }, "required": [ "id", "name", "updatedAt", "bidder", "searchConfig" ] } } } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" }, "instance": { "type": "string", "format": "uri" } }, "required": ["type", "title", "status", "detail", "instance"] } } } } }, "operationId": "postV1Job-searches", "tags": ["Job Searches"], "parameters": [], "summary": "Create a job search", "description": "Creates a new job-search configuration for the workspace.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "jobCategories": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "1.1", "1.2", "1.3", "1.4", "1.5", "1.6", "1.7", "2.1", "2.2", "2.3", "2.4", "2.5", "3.1", "3.2", "3.3", "4.1", "4.2", "4.3", "4.4", "4.5", "5.1", "5.2", "5.3", "5.4", "5.5", "5.6", "5.7", "5.8", "5.9", "5.10", "6.1", "6.2", "6.3", "6.4", "6.5", "6.6", "6.7", "6.8", "6.9", "6.10", "7.1", "7.2", "7.3", "7.4", "7.5", "7.6", "8.1", "8.2", "8.3", "8.4", "8.5", "9.1", "9.2", "9.3", "9.4", "10.1", "10.2", "10.3", "11.1", "11.2", "11.3", "11.4", "11.5", "11.6", "11.7", "11.8", "11.9", "11.10", "11.11", "11.12", "11.13", "12.1", "12.2", "12.3", "12.4", "12.5" ] }, "description": "Upwork category codes to include (e.g. `11.11` for \u201cMobile Development\u201d)." }, "excludeKeywords": { "type": ["object", "null"], "properties": { "active": { "type": "boolean", "description": "Indicates whether keywords are used to narrow the search" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "The list of keywords to search" }, "matchDescription": { "type": "boolean", "description": "Whether to match specified keywords against job descriptions" }, "matchSkills": { "type": "boolean", "description": "Whether to match specified keywords against job skills" }, "matchTitle": { "type": "boolean", "description": "Whether to match specified keywords against job titles" } }, "required": [ "active", "keywords", "matchDescription", "matchSkills", "matchTitle" ], "description": "Keywords that **must not** appear in title or description." }, "includeKeywords": { "type": ["object", "null"], "properties": { "active": { "type": "boolean", "description": "Indicates whether keywords are used to narrow the search" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "The list of keywords to search" }, "matchDescription": { "type": "boolean", "description": "Whether to match specified keywords against job descriptions" }, "matchSkills": { "type": "boolean", "description": "Whether to match specified keywords against job skills" }, "matchTitle": { "type": "boolean", "description": "Whether to match specified keywords against job titles" } }, "required": [ "active", "keywords", "matchDescription", "matchSkills", "matchTitle" ], "description": "Keywords that **must** appear in title or description." }, "budget": { "type": ["object", "null"], "properties": { "allowUnspecifiedBudget": { "type": ["boolean", "null"], "description": "Include job posts with no stated budget when `true`." }, "avgHourlyRate": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of a client\u2019s *average* hourly spend (USD)." }, "hourlyRate": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of the job\u2019s listed hourly rate (USD)." }, "connectsPrice": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of Connects required to bid." }, "fixedPrice": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of fixed-price budgets (USD)." }, "jobDurations": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "UNSPECIFIED", "UP_TO_ONE_MONTH", "UP_TO_THREE_MONTHS", "UP_TO_SIX_MONTHS", "MORE_THAN_SIX_MONTHS" ] }, "description": "Allowed contract durations." }, "hourlyWorkloads": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "UNSPECIFIED", "LESS_THAN_30_HOURS", "MORE_THAN_30_HOURS" ] }, "description": "Allowed weekly workloads." }, "noAvgHourlyRatePaid": { "type": ["boolean", "null"], "description": "Accept clients with no recorded average hourly rate." }, "noHireRate": { "type": ["boolean", "null"], "description": "Accept clients with zero hire rate." }, "onlyContractToHire": { "type": ["boolean", "null"], "description": "Limit to \u201cContract-to-hire\u201d postings." }, "minClientHireRate": { "type": ["number", "null"], "description": "Minimum client hire rate (%) required.", "example": 60 } }, "description": "Budget-related filters; `null` disables budget filtering." }, "client": { "type": ["object", "null"], "properties": { "companySizeRange": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "UNSPECIFIED", "SOLO_ENTERPRENEUR", "UP_TO_10_EMPLOYEES", "UP_TO_100_EMPOLOYEES", "UP_TO_500_EMPLOYEES", "UP_TO_1K_EMPLOYEES", "MORE_THAN_1K_EMPLOYEES" ] }, "description": "Allowed client company-size buckets." }, "descriptionLanguage": { "type": ["object", "null"], "properties": { "exclude": { "type": ["array", "null"], "items": { "type": "string" }, "description": "ISO-639-2 codes to exclude (e.g. `fra`)." }, "include": { "type": ["array", "null"], "items": { "type": "string" }, "description": "ISO-639-2 codes that must be present." } }, "description": "Language filters applied to job descriptions." }, "hireHistory": { "type": ["array", "null"], "items": { "type": "string", "enum": ["NONE", "UP_TO", "MORE_THAN"] }, "description": "Allowed buckets of previous hires made by the client." }, "includeLocations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["COUNTRY", "SUBREGION", "REGION"], "description": "Geographic granularity of the filter." }, "value": { "type": "string", "description": "Stable unique identifier." } }, "required": ["type", "value"] }, "description": "Locations filter" }, "excludeLocations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["COUNTRY", "SUBREGION", "REGION"], "description": "Geographic granularity of the filter." }, "value": { "type": "string", "description": "Stable unique identifier." } }, "required": ["type", "value"] }, "description": "Locations filter" }, "includeIndustry": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Industries that **must** match (by code or name)." }, "excludeIndustry": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Industries to exclude (by code or name)." }, "includeWithNoFeedback": { "type": ["boolean", "null"], "description": "Accept clients that have never received feedback." }, "totalSpent": { "type": ["object", "null", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Upper bound on client total spend (USD).", "example": { "min": 500, "max": null } }, "minFeedbackScore": { "type": ["number", "null"], "description": "Minimum average client feedback (0\u20135).", "example": 4.5 }, "paymentMethodVerified": { "type": ["boolean", "null"], "description": "Require the client\u2019s payment method to be verified." }, "phoneNumberVerified": { "type": ["boolean", "null"], "description": "Require the client\u2019s phone number to be verified." }, "timezones": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Allowed IANA time-zone identifiers.", "example": ["America/New_York", "Europe/London"] } }, "description": "Client-side filters; `null` disables them." }, "vendor": { "type": ["object", "null"], "properties": { "type": { "type": ["array", "null"], "items": { "type": "string", "enum": ["UNSPECIFIED", "FREELANCER", "AGENCY"] }, "description": "Allowed vendor contract types (e.g. `AGENCY`)." }, "languages": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Required vendor language codes (ISO-639-1)." }, "englishProficiency": { "type": ["string", "null"], "enum": [ "BASIC", "CONVERSATIONAL", "FLUENT", "NATIVE", null ], "description": "Minimum English proficiency level required." }, "experienceLevel": { "type": ["array", "null"], "items": { "type": "string", "enum": ["BEGINNER", "INTERMEDIATE", "EXPERT"] }, "description": "Allowed Upwork experience levels." }, "minGetmanyJobScore": { "type": ["number", "null"], "minimum": 0, "maximum": 5, "description": "Minimum Getmany Job Score (0-5) required", "example": 4.7 }, "includeLocations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["COUNTRY", "SUBREGION", "REGION"], "description": "Geographic granularity of the filter." }, "value": { "type": "string", "description": "Stable unique identifier." } }, "required": ["type", "value"] }, "description": "Locations filter" }, "includeFeatured": { "type": ["boolean", "null"], "description": "Limit to \u201cFeatured\u201d job posts." }, "includeWithoutCountryPreference": { "type": ["boolean", "null"], "description": "Include posts with no vendor location preference." }, "excludeWithQuestions": { "type": ["boolean", "null"], "description": "Exclude posts that contain screening questions." } }, "description": "Vendor-side (freelancer) filters; `null` disables them." } } } } } } } }, "/v1/job-searches/{id}": { "get": { "responses": { "200": { "description": "Job search object", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the job-search configuration", "example": "507f1f77bcf86cd799439011" }, "name": { "type": "string", "description": "Human-readable name of the job-search configuration", "example": "Mobile Dev \u2013 Long-term" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) of the last modification", "example": "2025-06-30T14:21:08Z" }, "bidder": { "type": "object", "properties": { "status": { "type": "string", "enum": ["not_configured", "active", "stopped"], "description": "Lifecycle state of the auto-bidder: `not_configured` \u2192 user has not provided settings; `active` \u2192 bidding is running; `stopped` \u2192 user paused bidding." }, "mode": { "type": ["string", "null"], "enum": ["template", "ai", null], "description": "Proposal composer engine. `template` = static template, `ai` = AI-generated. `null` when bidder is not configured." } }, "required": ["status", "mode"], "description": "Automated bidder configuration; omit or leave `null` to disable bidding." }, "searchConfig": { "type": "object", "properties": { "jobCategories": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "1.1", "1.2", "1.3", "1.4", "1.5", "1.6", "1.7", "2.1", "2.2", "2.3", "2.4", "2.5", "3.1", "3.2", "3.3", "4.1", "4.2", "4.3", "4.4", "4.5", "5.1", "5.2", "5.3", "5.4", "5.5", "5.6", "5.7", "5.8", "5.9", "5.10", "6.1", "6.2", "6.3", "6.4", "6.5", "6.6", "6.7", "6.8", "6.9", "6.10", "7.1", "7.2", "7.3", "7.4", "7.5", "7.6", "8.1", "8.2", "8.3", "8.4", "8.5", "9.1", "9.2", "9.3", "9.4", "10.1", "10.2", "10.3", "11.1", "11.2", "11.3", "11.4", "11.5", "11.6", "11.7", "11.8", "11.9", "11.10", "11.11", "11.12", "11.13", "12.1", "12.2", "12.3", "12.4", "12.5" ] }, "description": "Upwork category codes to include (e.g. `11.11` for \u201cMobile Development\u201d)." }, "excludeKeywords": { "type": ["object", "null"], "properties": { "active": { "type": "boolean", "description": "Indicates whether keywords are used to narrow the search" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "The list of keywords to search" }, "matchDescription": { "type": "boolean", "description": "Whether to match specified keywords against job descriptions" }, "matchSkills": { "type": "boolean", "description": "Whether to match specified keywords against job skills" }, "matchTitle": { "type": "boolean", "description": "Whether to match specified keywords against job titles" } }, "required": [ "active", "keywords", "matchDescription", "matchSkills", "matchTitle" ], "description": "Keywords that **must not** appear in title or description." }, "includeKeywords": { "type": ["object", "null"], "properties": { "active": { "type": "boolean", "description": "Indicates whether keywords are used to narrow the search" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "The list of keywords to search" }, "matchDescription": { "type": "boolean", "description": "Whether to match specified keywords against job descriptions" }, "matchSkills": { "type": "boolean", "description": "Whether to match specified keywords against job skills" }, "matchTitle": { "type": "boolean", "description": "Whether to match specified keywords against job titles" } }, "required": [ "active", "keywords", "matchDescription", "matchSkills", "matchTitle" ], "description": "Keywords that **must** appear in title or description." }, "budget": { "type": ["object", "null"], "properties": { "allowUnspecifiedBudget": { "type": ["boolean", "null"], "description": "Include job posts with no stated budget when `true`." }, "avgHourlyRate": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of a client\u2019s *average* hourly spend (USD)." }, "hourlyRate": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of the job\u2019s listed hourly rate (USD)." }, "connectsPrice": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of Connects required to bid." }, "fixedPrice": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of fixed-price budgets (USD)." }, "jobDurations": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "UNSPECIFIED", "UP_TO_ONE_MONTH", "UP_TO_THREE_MONTHS", "UP_TO_SIX_MONTHS", "MORE_THAN_SIX_MONTHS" ] }, "description": "Allowed contract durations." }, "hourlyWorkloads": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "UNSPECIFIED", "LESS_THAN_30_HOURS", "MORE_THAN_30_HOURS" ] }, "description": "Allowed weekly workloads." }, "noAvgHourlyRatePaid": { "type": ["boolean", "null"], "description": "Accept clients with no recorded average hourly rate." }, "noHireRate": { "type": ["boolean", "null"], "description": "Accept clients with zero hire rate." }, "onlyContractToHire": { "type": ["boolean", "null"], "description": "Limit to \u201cContract-to-hire\u201d postings." }, "minClientHireRate": { "type": ["number", "null"], "description": "Minimum client hire rate (%) required.", "example": 60 } }, "description": "Budget-related filters; `null` disables budget filtering." }, "client": { "type": ["object", "null"], "properties": { "companySizeRange": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "UNSPECIFIED", "SOLO_ENTERPRENEUR", "UP_TO_10_EMPLOYEES", "UP_TO_100_EMPOLOYEES", "UP_TO_500_EMPLOYEES", "UP_TO_1K_EMPLOYEES", "MORE_THAN_1K_EMPLOYEES" ] }, "description": "Allowed client company-size buckets." }, "descriptionLanguage": { "type": ["object", "null"], "properties": { "exclude": { "type": ["array", "null"], "items": { "type": "string" }, "description": "ISO-639-2 codes to exclude (e.g. `fra`)." }, "include": { "type": ["array", "null"], "items": { "type": "string" }, "description": "ISO-639-2 codes that must be present." } }, "description": "Language filters applied to job descriptions." }, "hireHistory": { "type": ["array", "null"], "items": { "type": "string", "enum": ["NONE", "UP_TO", "MORE_THAN"] }, "description": "Allowed buckets of previous hires made by the client." }, "includeLocations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COUNTRY", "SUBREGION", "REGION" ], "description": "Geographic granularity of the filter." }, "value": { "type": "string", "description": "Stable unique identifier." } }, "required": ["type", "value"] }, "description": "Locations filter" }, "excludeLocations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COUNTRY", "SUBREGION", "REGION" ], "description": "Geographic granularity of the filter." }, "value": { "type": "string", "description": "Stable unique identifier." } }, "required": ["type", "value"] }, "description": "Locations filter" }, "includeIndustry": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Industries that **must** match (by code or name)." }, "excludeIndustry": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Industries to exclude (by code or name)." }, "includeWithNoFeedback": { "type": ["boolean", "null"], "description": "Accept clients that have never received feedback." }, "totalSpent": { "type": ["object", "null", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Upper bound on client total spend (USD).", "example": { "min": 500, "max": null } }, "minFeedbackScore": { "type": ["number", "null"], "description": "Minimum average client feedback (0\u20135).", "example": 4.5 }, "paymentMethodVerified": { "type": ["boolean", "null"], "description": "Require the client\u2019s payment method to be verified." }, "phoneNumberVerified": { "type": ["boolean", "null"], "description": "Require the client\u2019s phone number to be verified." }, "timezones": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Allowed IANA time-zone identifiers.", "example": [ "America/New_York", "Europe/London" ] } }, "description": "Client-side filters; `null` disables them." }, "vendor": { "type": ["object", "null"], "properties": { "type": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "UNSPECIFIED", "FREELANCER", "AGENCY" ] }, "description": "Allowed vendor contract types (e.g. `AGENCY`)." }, "languages": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Required vendor language codes (ISO-639-1)." }, "englishProficiency": { "type": ["string", "null"], "enum": [ "BASIC", "CONVERSATIONAL", "FLUENT", "NATIVE", null ], "description": "Minimum English proficiency level required." }, "experienceLevel": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "BEGINNER", "INTERMEDIATE", "EXPERT" ] }, "description": "Allowed Upwork experience levels." }, "minGetmanyJobScore": { "type": ["number", "null"], "minimum": 0, "maximum": 5, "description": "Minimum Getmany Job Score (0-5) required", "example": 4.7 }, "includeLocations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COUNTRY", "SUBREGION", "REGION" ], "description": "Geographic granularity of the filter." }, "value": { "type": "string", "description": "Stable unique identifier." } }, "required": ["type", "value"] }, "description": "Locations filter" }, "includeFeatured": { "type": ["boolean", "null"], "description": "Limit to \u201cFeatured\u201d job posts." }, "includeWithoutCountryPreference": { "type": ["boolean", "null"], "description": "Include posts with no vendor location preference." }, "excludeWithQuestions": { "type": ["boolean", "null"], "description": "Exclude posts that contain screening questions." } }, "description": "Vendor-side (freelancer) filters; `null` disables them." } }, "description": "Grouping of all job-search filter parameters." } }, "required": [ "id", "name", "updatedAt", "bidder", "searchConfig" ] } } } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" }, "instance": { "type": "string", "format": "uri" } }, "required": ["type", "title", "status", "detail", "instance"] } } } } }, "operationId": "getV1Job-searchesById", "tags": ["Job Searches"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "summary": "Get a job search", "description": "Fetch a single job-search configuration and its current statistics." } }, "/v1/job-searches/{id}/stats": { "get": { "responses": { "200": { "description": "Stats object", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sent": { "type": "number", "description": "Total proposals submitted.", "example": 150 }, "viewed": { "type": "number", "description": "Proposals the client opened in Upwork UI.", "example": 42 }, "accepted": { "type": "number", "description": "Proposals that moved to an \u201cInterview\u201d state.", "example": 18 }, "hired": { "type": "number", "description": "Proposals that resulted in a contract.", "example": 7 }, "conversionRate": { "type": "number", "description": "Optional percentage `(hired \u00f7 sent) \u00d7 100`. Left undefined when `sent` is 0.", "example": 4.67 } }, "required": ["sent", "viewed", "accepted", "hired"], "description": "Counts of proposals at each lifecycle stage." } } } } } } }, "operationId": "getV1Job-searchesByIdStats", "tags": ["Job Searches"], "parameters": [ { "in": "query", "name": "from", "schema": { "type": "string", "format": "date-time" }, "required": true }, { "in": "query", "name": "to", "schema": { "type": "string", "format": "date-time" }, "required": true }, { "in": "query", "name": "include", "schema": { "type": "string", "const": "conversion_rate" }, "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "summary": "Retrieve performance metrics for a Job Search", "description": "Aggregated proposal stats for a given date range." } }, "/v1/job-searches/feed-preview": { "post": { "responses": { "200": { "description": "Matches jobs list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uid": { "type": "string", "description": "Unique ID of the posting on Upwork" }, "title": { "type": "string", "description": "Job title" }, "description": { "type": "string", "description": "Detailed job description provided by customer" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) of the last modification", "example": "2025-06-30T14:21:08Z" }, "skills": { "type": "array", "items": { "type": "string" }, "description": "The list of skill ontologies (their labels)", "example": ["React.js", "React Router", "Redux"] }, "externalLink": { "type": "string", "format": "uri", "description": "The direct link to the posting on Upwork", "example": "https://www.upwork.com/jobs/~021940001497348327923" }, "applicationCost": { "type": "number", "description": "Number of connects required to send an application" }, "featured": { "type": "boolean", "description": "Is premium job posting?" }, "category": { "type": "string", "description": "Main category of job posting", "example": "Web Development" }, "ciphertext": { "type": "string", "description": "The secondary ID of the posting" }, "getmanyJobScore": { "type": "number", "minimum": 1, "maximum": 5, "description": "Internal Getmany score" }, "questions": { "type": "array", "items": { "type": "string" }, "description": "The list of questions from the client" }, "budget": { "type": "object", "properties": { "fixedBudget": { "type": ["number", "null"] }, "hourlyRate": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } } } }, "description": "Budget terms of the job posting" }, "client": { "type": "object", "properties": { "name": { "type": ["string", "null"] }, "timezone": { "type": "string" }, "industry": { "type": "string" }, "companySize": { "type": "number" }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "phoneNumberVerified": { "type": "boolean" }, "paymentMethodVerified": { "type": "boolean" }, "enterprise": { "type": "boolean", "description": "Is enterprise tier customer" }, "connectedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) of the last modification", "example": "2025-06-30T14:21:08Z" }, "stats": { "type": "object", "properties": { "totalSpent": { "type": "number" }, "totalHires": { "type": "number" }, "hireRate": { "type": "number" }, "avgRate": { "type": "number" }, "feedbackRate": { "type": "number" }, "feedbackCount": { "type": "number" } } } }, "description": "Details about the client who posted the job" }, "vendor": { "type": "object", "properties": { "hireType": { "type": "string", "enum": ["ANY", "INDEPENDENT", "AGENCY"] }, "countryCodes": { "type": "array", "items": { "type": "string" } }, "experienceLevel": { "type": "string", "enum": ["BEGINNER", "INTERMEDIATE", "EXPERT"] }, "englishLevel": { "type": "string", "enum": [ "ANY", "CONVERSATIONAL", "FLUENT", "NATIVE" ] } }, "description": "Client's requirements to the contractor" } } } } } } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" }, "instance": { "type": "string", "format": "uri" } }, "required": ["type", "title", "status", "detail", "instance"] } } } } }, "operationId": "postV1Job-searchesFeed-preview", "tags": ["Jobs Feed"], "parameters": [ { "in": "query", "name": "pageOffset", "schema": { "type": "string" } }, { "in": "query", "name": "pageSize", "schema": { "type": "string" } }, { "in": "query", "name": "fromDate", "schema": { "type": "string" } }, { "in": "query", "name": "toDate", "schema": { "type": "string" } } ], "summary": "Create a job feed preview", "description": "At any time, you can create a job feed preview to verify what jobs will match with a given configuration.\n\nNote that this endpoint doesn't create a job search.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "jobCategories": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "1.1", "1.2", "1.3", "1.4", "1.5", "1.6", "1.7", "2.1", "2.2", "2.3", "2.4", "2.5", "3.1", "3.2", "3.3", "4.1", "4.2", "4.3", "4.4", "4.5", "5.1", "5.2", "5.3", "5.4", "5.5", "5.6", "5.7", "5.8", "5.9", "5.10", "6.1", "6.2", "6.3", "6.4", "6.5", "6.6", "6.7", "6.8", "6.9", "6.10", "7.1", "7.2", "7.3", "7.4", "7.5", "7.6", "8.1", "8.2", "8.3", "8.4", "8.5", "9.1", "9.2", "9.3", "9.4", "10.1", "10.2", "10.3", "11.1", "11.2", "11.3", "11.4", "11.5", "11.6", "11.7", "11.8", "11.9", "11.10", "11.11", "11.12", "11.13", "12.1", "12.2", "12.3", "12.4", "12.5" ] }, "description": "Upwork category codes to include (e.g. `11.11` for \u201cMobile Development\u201d)." }, "excludeKeywords": { "type": ["object", "null"], "properties": { "active": { "type": "boolean", "description": "Indicates whether keywords are used to narrow the search" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "The list of keywords to search" }, "matchDescription": { "type": "boolean", "description": "Whether to match specified keywords against job descriptions" }, "matchSkills": { "type": "boolean", "description": "Whether to match specified keywords against job skills" }, "matchTitle": { "type": "boolean", "description": "Whether to match specified keywords against job titles" } }, "required": [ "active", "keywords", "matchDescription", "matchSkills", "matchTitle" ], "description": "Keywords that **must not** appear in title or description." }, "includeKeywords": { "type": ["object", "null"], "properties": { "active": { "type": "boolean", "description": "Indicates whether keywords are used to narrow the search" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "The list of keywords to search" }, "matchDescription": { "type": "boolean", "description": "Whether to match specified keywords against job descriptions" }, "matchSkills": { "type": "boolean", "description": "Whether to match specified keywords against job skills" }, "matchTitle": { "type": "boolean", "description": "Whether to match specified keywords against job titles" } }, "required": [ "active", "keywords", "matchDescription", "matchSkills", "matchTitle" ], "description": "Keywords that **must** appear in title or description." }, "budget": { "type": ["object", "null"], "properties": { "allowUnspecifiedBudget": { "type": ["boolean", "null"], "description": "Include job posts with no stated budget when `true`." }, "avgHourlyRate": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of a client\u2019s *average* hourly spend (USD)." }, "hourlyRate": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of the job\u2019s listed hourly rate (USD)." }, "connectsPrice": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of Connects required to bid." }, "fixedPrice": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Allowed range of fixed-price budgets (USD)." }, "jobDurations": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "UNSPECIFIED", "UP_TO_ONE_MONTH", "UP_TO_THREE_MONTHS", "UP_TO_SIX_MONTHS", "MORE_THAN_SIX_MONTHS" ] }, "description": "Allowed contract durations." }, "hourlyWorkloads": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "UNSPECIFIED", "LESS_THAN_30_HOURS", "MORE_THAN_30_HOURS" ] }, "description": "Allowed weekly workloads." }, "noAvgHourlyRatePaid": { "type": ["boolean", "null"], "description": "Accept clients with no recorded average hourly rate." }, "noHireRate": { "type": ["boolean", "null"], "description": "Accept clients with zero hire rate." }, "onlyContractToHire": { "type": ["boolean", "null"], "description": "Limit to \u201cContract-to-hire\u201d postings." }, "minClientHireRate": { "type": ["number", "null"], "description": "Minimum client hire rate (%) required.", "example": 60 } }, "description": "Budget-related filters; `null` disables budget filtering." }, "client": { "type": ["object", "null"], "properties": { "companySizeRange": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "UNSPECIFIED", "SOLO_ENTERPRENEUR", "UP_TO_10_EMPLOYEES", "UP_TO_100_EMPOLOYEES", "UP_TO_500_EMPLOYEES", "UP_TO_1K_EMPLOYEES", "MORE_THAN_1K_EMPLOYEES" ] }, "description": "Allowed client company-size buckets." }, "descriptionLanguage": { "type": ["object", "null"], "properties": { "exclude": { "type": ["array", "null"], "items": { "type": "string" }, "description": "ISO-639-2 codes to exclude (e.g. `fra`)." }, "include": { "type": ["array", "null"], "items": { "type": "string" }, "description": "ISO-639-2 codes that must be present." } }, "description": "Language filters applied to job descriptions." }, "hireHistory": { "type": ["array", "null"], "items": { "type": "string", "enum": ["NONE", "UP_TO", "MORE_THAN"] }, "description": "Allowed buckets of previous hires made by the client." }, "includeLocations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["COUNTRY", "SUBREGION", "REGION"], "description": "Geographic granularity of the filter." }, "value": { "type": "string", "description": "Stable unique identifier." } }, "required": ["type", "value"] }, "description": "Locations filter" }, "excludeLocations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["COUNTRY", "SUBREGION", "REGION"], "description": "Geographic granularity of the filter." }, "value": { "type": "string", "description": "Stable unique identifier." } }, "required": ["type", "value"] }, "description": "Locations filter" }, "includeIndustry": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Industries that **must** match (by code or name)." }, "excludeIndustry": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Industries to exclude (by code or name)." }, "includeWithNoFeedback": { "type": ["boolean", "null"], "description": "Accept clients that have never received feedback." }, "totalSpent": { "type": ["object", "null", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } }, "description": "Upper bound on client total spend (USD).", "example": { "min": 500, "max": null } }, "minFeedbackScore": { "type": ["number", "null"], "description": "Minimum average client feedback (0\u20135).", "example": 4.5 }, "paymentMethodVerified": { "type": ["boolean", "null"], "description": "Require the client\u2019s payment method to be verified." }, "phoneNumberVerified": { "type": ["boolean", "null"], "description": "Require the client\u2019s phone number to be verified." }, "timezones": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Allowed IANA time-zone identifiers.", "example": ["America/New_York", "Europe/London"] } }, "description": "Client-side filters; `null` disables them." }, "vendor": { "type": ["object", "null"], "properties": { "type": { "type": ["array", "null"], "items": { "type": "string", "enum": ["UNSPECIFIED", "FREELANCER", "AGENCY"] }, "description": "Allowed vendor contract types (e.g. `AGENCY`)." }, "languages": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Required vendor language codes (ISO-639-1)." }, "englishProficiency": { "type": ["string", "null"], "enum": [ "BASIC", "CONVERSATIONAL", "FLUENT", "NATIVE", null ], "description": "Minimum English proficiency level required." }, "experienceLevel": { "type": ["array", "null"], "items": { "type": "string", "enum": ["BEGINNER", "INTERMEDIATE", "EXPERT"] }, "description": "Allowed Upwork experience levels." }, "minGetmanyJobScore": { "type": ["number", "null"], "minimum": 0, "maximum": 5, "description": "Minimum Getmany Job Score (0-5) required", "example": 4.7 }, "includeLocations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["COUNTRY", "SUBREGION", "REGION"], "description": "Geographic granularity of the filter." }, "value": { "type": "string", "description": "Stable unique identifier." } }, "required": ["type", "value"] }, "description": "Locations filter" }, "includeFeatured": { "type": ["boolean", "null"], "description": "Limit to \u201cFeatured\u201d job posts." }, "includeWithoutCountryPreference": { "type": ["boolean", "null"], "description": "Include posts with no vendor location preference." }, "excludeWithQuestions": { "type": ["boolean", "null"], "description": "Exclude posts that contain screening questions." } }, "description": "Vendor-side (freelancer) filters; `null` disables them." } } } } } } } }, "/v1/job-searches/{id}/feed": { "get": { "responses": { "200": { "description": "Match list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uid": { "type": "string", "description": "Unique ID of the posting on Upwork" }, "title": { "type": "string", "description": "Job title" }, "description": { "type": "string", "description": "Detailed job description provided by customer" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) of the last modification", "example": "2025-06-30T14:21:08Z" }, "skills": { "type": "array", "items": { "type": "string" }, "description": "The list of skill ontologies (their labels)", "example": ["React.js", "React Router", "Redux"] }, "externalLink": { "type": "string", "format": "uri", "description": "The direct link to the posting on Upwork", "example": "https://www.upwork.com/jobs/~021940001497348327923" }, "applicationCost": { "type": "number", "description": "Number of connects required to send an application" }, "featured": { "type": "boolean", "description": "Is premium job posting?" }, "category": { "type": "string", "description": "Main category of job posting", "example": "Web Development" }, "ciphertext": { "type": "string", "description": "The secondary ID of the posting" }, "getmanyJobScore": { "type": "number", "minimum": 1, "maximum": 5, "description": "Internal Getmany score" }, "questions": { "type": "array", "items": { "type": "string" }, "description": "The list of questions from the client" }, "budget": { "type": "object", "properties": { "fixedBudget": { "type": ["number", "null"] }, "hourlyRate": { "type": ["object", "null"], "properties": { "min": { "type": ["number", "null"], "description": "Range lower bound" }, "max": { "type": ["number", "null"], "description": "Range upper bound" } } } }, "description": "Budget terms of the job posting" }, "client": { "type": "object", "properties": { "name": { "type": ["string", "null"] }, "timezone": { "type": "string" }, "industry": { "type": "string" }, "companySize": { "type": "number" }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "phoneNumberVerified": { "type": "boolean" }, "paymentMethodVerified": { "type": "boolean" }, "enterprise": { "type": "boolean", "description": "Is enterprise tier customer" }, "connectedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC) of the last modification", "example": "2025-06-30T14:21:08Z" }, "stats": { "type": "object", "properties": { "totalSpent": { "type": "number" }, "totalHires": { "type": "number" }, "hireRate": { "type": "number" }, "avgRate": { "type": "number" }, "feedbackRate": { "type": "number" }, "feedbackCount": { "type": "number" } } } }, "description": "Details about the client who posted the job" }, "vendor": { "type": "object", "properties": { "hireType": { "type": "string", "enum": ["ANY", "INDEPENDENT", "AGENCY"] }, "countryCodes": { "type": "array", "items": { "type": "string" } }, "experienceLevel": { "type": "string", "enum": ["BEGINNER", "INTERMEDIATE", "EXPERT"] }, "englishLevel": { "type": "string", "enum": [ "ANY", "CONVERSATIONAL", "FLUENT", "NATIVE" ] } }, "description": "Client's requirements to the contractor" } } } } } } } } } }, "operationId": "getV1Job-searchesByIdFeed", "tags": ["Jobs Feed"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "pageCursor", "schema": { "type": "string" } }, { "in": "query", "name": "pageSize", "schema": { "type": "string" } }, { "in": "query", "name": "since", "schema": { "type": "string", "format": "date-time" } } ], "summary": "List recent job matches", "description": "Returns job postings that matched the specified job search." } }, "/v1/job-categories": { "get": { "responses": { "200": { "description": "Categories list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Id of the category", "example": "11.11" }, "name": { "type": "string", "description": "Category name", "example": "Web Development" } }, "required": ["id", "name"] } } } } } } } }, "operationId": "getV1Job-categories", "tags": ["Miscellaneous"], "parameters": [], "summary": "List job categories", "description": "Returns a list of job categories available on Upwork" } }, "/v1/bid-intents/{id}": { "delete": { "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } } } } }, "operationId": "deleteV1Bid-intentsById", "tags": ["Bid Intents"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bid intent ID" } ], "summary": "Cancel bid", "description": "Cancels a scheduled bid intent by its ID" } }, "/v1/misc/regions": { "get": { "responses": { "200": { "description": "Regions list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "region" }, "uid": { "type": "string", "description": "Unique stable identified of the region", "example": "americas" }, "value": { "type": "string", "description": "Region name", "example": "Americas" } }, "required": ["type", "uid", "value"] } } } } } } } }, "operationId": "getV1MiscRegions", "tags": ["Miscellaneous"], "parameters": [], "summary": "List regions", "description": "Returns a list of geographical regions available on Upwork" } }, "/v1/misc/sub-regions": { "get": { "responses": { "200": { "description": "Regions list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "subregion" }, "uid": { "type": "string", "description": "Unique stable identified of the subregion", "example": "australia-and-new-zealand" }, "value": { "type": "string", "description": "Region name", "example": "Australia and New Zealand" }, "regionUid": { "type": "string", "description": "Parent region indentified", "example": "oceania" } }, "required": ["type", "uid", "value", "regionUid"] } } } } } } } }, "operationId": "getV1MiscSub-regions", "tags": ["Miscellaneous"], "parameters": [], "summary": "List sub regions", "description": "Returns a list of geographical sub regions available on Upwork" } }, "/v1/master-inbox/rooms": { "get": { "responses": { "200": { "description": "Paginated chat rooms list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "roomId": { "type": "string", "description": "Upwork room identifier." }, "roomName": { "type": ["string", "null"], "description": "Display name of the room." }, "topic": { "type": ["string", "null"], "description": "Room topic." }, "roomType": { "type": ["string", "null"], "description": "GROUP, INTERVIEW, or ONE_ON_ONE." }, "roomUsers": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "description": "Upwork user ID." }, "nid": { "type": ["string", "null"], "description": "Upwork NID." }, "rid": { "type": ["string", "null"], "description": "Upwork RID." }, "name": { "type": ["string", "null"], "description": "Display name." }, "photoUrl": { "type": ["string", "null"], "description": "Avatar URL." } }, "required": [ "id", "nid", "rid", "name", "photoUrl" ] }, "organization": { "type": ["object", "null"], "properties": { "id": { "type": ["string", "null"], "description": "Organization ID." }, "name": { "type": ["string", "null"], "description": "Organization name." }, "type": { "type": ["string", "null"], "description": "BUSINESS or SOLE_PROPRIETOR." }, "photoUrl": { "type": ["string", "null"], "description": "Organization photo URL." } }, "required": ["id", "name", "type", "photoUrl"] }, "role": { "type": ["string", "null"], "description": "Participant role." } }, "required": ["user", "organization", "role"] }, "description": "Participants in the chat room." }, "lastStory": { "type": ["object", "null"], "properties": { "storyId": { "type": "string", "description": "Upwork story ID." }, "message": { "type": "string", "description": "Message text." }, "user": { "type": ["object", "null"], "properties": { "id": { "type": "string", "description": "Upwork user ID." }, "nid": { "type": ["string", "null"], "description": "Upwork NID." }, "rid": { "type": ["string", "null"], "description": "Upwork RID." }, "name": { "type": ["string", "null"], "description": "Display name." }, "photoUrl": { "type": ["string", "null"], "description": "Avatar URL." } }, "required": [ "id", "nid", "rid", "name", "photoUrl" ] }, "createdDateTime": { "type": "string", "format": "date-time", "description": "When the message was sent (ISO-8601)." }, "updatedDateTime": { "type": ["string", "null"], "format": "date-time", "description": "When the message was last updated (ISO-8601)." }, "attachments": { "type": ["array", "null"], "items": { "type": "object", "properties": { "objectReferenceId": { "type": ["string", "null"] }, "objectType": { "type": ["string", "null"] }, "createdDateTime": { "type": ["string", "null"], "format": "date-time" }, "author": { "type": ["object", "null"], "properties": { "user": { "type": ["object", "null"], "properties": { "id": { "type": "string", "description": "Upwork user ID." }, "nid": { "type": ["string", "null"], "description": "Upwork NID." }, "rid": { "type": ["string", "null"], "description": "Upwork RID." }, "name": { "type": ["string", "null"], "description": "Display name." }, "photoUrl": { "type": ["string", "null"], "description": "Avatar URL." } }, "required": [ "id", "nid", "rid", "name", "photoUrl" ] }, "organization": { "type": ["object", "null"], "properties": { "id": { "type": ["string", "null"], "description": "Organization ID." }, "name": { "type": ["string", "null"], "description": "Organization name." }, "type": { "type": ["string", "null"], "description": "BUSINESS or SOLE_PROPRIETOR." }, "photoUrl": { "type": ["string", "null"], "description": "Organization photo URL." } }, "required": [ "id", "name", "type", "photoUrl" ] }, "role": { "type": ["string", "null"] } }, "required": [ "user", "organization", "role" ] }, "metadata": { "type": ["array", "null"], "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": ["key", "value"] } } }, "required": [ "objectReferenceId", "objectType", "createdDateTime", "author", "metadata" ] }, "description": "Message attachments." } }, "required": [ "storyId", "message", "user", "createdDateTime", "updatedDateTime", "attachments" ], "description": "Most recent message in the room." }, "unreadCount": { "type": "number", "description": "Number of unread messages." }, "organization": { "type": ["object", "null"], "properties": { "id": { "type": ["string", "null"], "description": "Organization ID." }, "name": { "type": ["string", "null"], "description": "Organization name." }, "type": { "type": ["string", "null"], "description": "BUSINESS or SOLE_PROPRIETOR." }, "photoUrl": { "type": ["string", "null"], "description": "Organization photo URL." } }, "required": ["id", "name", "type", "photoUrl"], "description": "Room organization (client)." }, "creator": { "type": ["object", "null"], "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "description": "Upwork user ID." }, "nid": { "type": ["string", "null"], "description": "Upwork NID." }, "rid": { "type": ["string", "null"], "description": "Upwork RID." }, "name": { "type": ["string", "null"], "description": "Display name." }, "photoUrl": { "type": ["string", "null"], "description": "Avatar URL." } }, "required": [ "id", "nid", "rid", "name", "photoUrl" ] }, "organization": { "type": ["object", "null"], "properties": { "id": { "type": ["string", "null"], "description": "Organization ID." }, "name": { "type": ["string", "null"], "description": "Organization name." }, "type": { "type": ["string", "null"], "description": "BUSINESS or SOLE_PROPRIETOR." }, "photoUrl": { "type": ["string", "null"], "description": "Organization photo URL." } }, "required": ["id", "name", "type", "photoUrl"] }, "role": { "type": ["string", "null"], "description": "Participant role." } }, "required": ["user", "organization", "role"], "description": "User who created the room." }, "owner": { "type": ["object", "null"], "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "description": "Upwork user ID." }, "nid": { "type": ["string", "null"], "description": "Upwork NID." }, "rid": { "type": ["string", "null"], "description": "Upwork RID." }, "name": { "type": ["string", "null"], "description": "Display name." }, "photoUrl": { "type": ["string", "null"], "description": "Avatar URL." } }, "required": [ "id", "nid", "rid", "name", "photoUrl" ] }, "organization": { "type": ["object", "null"], "properties": { "id": { "type": ["string", "null"], "description": "Organization ID." }, "name": { "type": ["string", "null"], "description": "Organization name." }, "type": { "type": ["string", "null"], "description": "BUSINESS or SOLE_PROPRIETOR." }, "photoUrl": { "type": ["string", "null"], "description": "Organization photo URL." } }, "required": ["id", "name", "type", "photoUrl"] }, "role": { "type": ["string", "null"], "description": "Participant role." } }, "required": ["user", "organization", "role"], "description": "Room owner." }, "vendorProposal": { "type": ["object", "null"], "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "marketplaceJobPostingId": { "type": "string" } }, "required": [ "id", "userId", "marketplaceJobPostingId" ], "description": "Linked vendor proposal." }, "contract": { "type": ["object", "null"], "properties": { "id": { "type": ["string", "null"] }, "title": { "type": ["string", "null"] }, "contractType": { "type": ["string", "null"] }, "status": { "type": ["string", "null"] }, "createdDateTime": { "type": ["string", "null"], "format": "date-time" }, "startDateTime": { "type": ["string", "null"], "format": "date-time" }, "endDateTime": { "type": ["string", "null"], "format": "date-time" } }, "required": [ "id", "title", "contractType", "status", "createdDateTime", "startDateTime", "endDateTime" ], "description": "Linked contract." }, "contractId": { "type": ["string", "null"], "description": "Contract ID if linked." }, "roomNote": { "type": ["string", "null"], "description": "Internal note on the room." }, "roomNotePresent": { "type": "boolean", "description": "Whether the room has a note." }, "isPublic": { "type": "boolean", "description": "Whether the room is public." }, "favorite": { "type": "boolean", "description": "Whether the room is marked as favorite." }, "readOnly": { "type": "boolean", "description": "Whether the room is read-only." }, "hidden": { "type": "boolean", "description": "Whether the room is hidden." }, "muted": { "type": "boolean", "description": "Whether the room is muted." }, "blockDateTime": { "type": ["string", "null"], "format": "date-time", "description": "When the room was blocked (ISO-8601)." }, "blockedBy": { "type": ["object", "null"], "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "description": "Upwork user ID." }, "nid": { "type": ["string", "null"], "description": "Upwork NID." }, "rid": { "type": ["string", "null"], "description": "Upwork RID." }, "name": { "type": ["string", "null"], "description": "Display name." }, "photoUrl": { "type": ["string", "null"], "description": "Avatar URL." } }, "required": [ "id", "nid", "rid", "name", "photoUrl" ] }, "organization": { "type": ["object", "null"], "properties": { "id": { "type": ["string", "null"], "description": "Organization ID." }, "name": { "type": ["string", "null"], "description": "Organization name." }, "type": { "type": ["string", "null"], "description": "BUSINESS or SOLE_PROPRIETOR." }, "photoUrl": { "type": ["string", "null"], "description": "Organization photo URL." } }, "required": ["id", "name", "type", "photoUrl"] }, "role": { "type": ["string", "null"], "description": "Participant role." } }, "required": ["user", "organization", "role"], "description": "User who blocked the room." }, "lastStoryId": { "type": ["string", "null"], "description": "ID of the most recent story." }, "lastStoryAt": { "type": ["string", "null"], "format": "date-time", "description": "When the last story was sent (ISO-8601)." }, "lastSyncedAt": { "type": ["string", "null"], "format": "date-time", "description": "When the room was last synced (ISO-8601)." }, "numUsers": { "type": ["number", "null"], "description": "Number of users in the room." }, "storiesCount": { "type": ["number", "null"], "description": "Total number of messages synced." }, "createdAtDateTime": { "type": ["string", "null"], "format": "date-time", "description": "When the room was created (ISO-8601)." } }, "required": [ "roomId", "roomName", "topic", "roomType", "roomUsers", "lastStory", "unreadCount", "organization", "creator", "owner", "vendorProposal", "contract", "contractId", "roomNote", "roomNotePresent", "isPublic", "favorite", "readOnly", "hidden", "muted", "blockDateTime", "blockedBy", "lastStoryId", "lastStoryAt", "lastSyncedAt", "numUsers", "storiesCount", "createdAtDateTime" ] } }, "meta": { "type": "object", "properties": { "pageSize": { "type": "number" }, "nextCursor": { "type": ["string", "null"] } }, "required": ["pageSize", "nextCursor"] } }, "required": ["data", "meta"] } } } }, "404": { "description": "Agency not found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" }, "instance": { "type": "string", "format": "uri" } }, "required": ["type", "title", "status", "detail", "instance"] } } } } }, "operationId": "getV1Master-inboxRooms", "tags": ["Master Inbox"], "parameters": [ { "in": "query", "name": "pageCursor", "schema": { "type": "string" } }, { "in": "query", "name": "pageSize", "schema": { "type": "string" } }, { "in": "query", "name": "search", "schema": { "type": "string" } }, { "in": "query", "name": "participants", "schema": { "type": "string" } }, { "in": "query", "name": "sort", "schema": { "type": "string", "enum": ["date-desc", "date-asc"], "description": "Sort order for chat rooms.", "default": "date-desc" } }, { "in": "query", "name": "clientMessageOnly", "schema": { "type": "string", "enum": ["true", "false"] } } ], "summary": "List chat rooms", "description": "Returns a paginated list of chat rooms for the workspace's agency. Supports filtering by archived status, search, participants, pipeline stages, client-only messages, and multiple sort modes with cursor-based pagination." } }, "/v1/master-inbox/rooms/{roomId}/stories": { "get": { "responses": { "200": { "description": "Paginated chat stories with room participants", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "storyId": { "type": "string", "description": "Upwork story ID." }, "userId": { "type": ["string", "null"], "description": "Upwork user ID of the sender." }, "userName": { "type": "string", "description": "Display name of the sender." }, "userPhotoUrl": { "type": "string", "description": "Avatar URL of the sender." }, "message": { "type": "string", "description": "Message text content." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the message was sent (ISO-8601)." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "objectReferenceId": { "type": "string", "description": "Reference ID of the attached object." }, "objectType": { "type": "string", "description": "Type of the attached object." }, "metadata": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Metadata key." }, "value": { "type": "string", "description": "Metadata value." } }, "required": ["key", "value"] }, "description": "Key-value metadata pairs for the attachment." } } }, "description": "Message attachments." } }, "required": [ "storyId", "userId", "userName", "userPhotoUrl", "message", "createdAt" ] } }, "meta": { "type": "object", "properties": { "pageSize": { "type": "number" }, "nextCursor": { "type": ["string", "null"] } }, "required": ["pageSize", "nextCursor"] } }, "required": ["data", "meta"] } } } }, "404": { "description": "Room not found or deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" }, "instance": { "type": "string", "format": "uri" } }, "required": ["type", "title", "status", "detail", "instance"] } } } } }, "operationId": "getV1Master-inboxRoomsByRoomIdStories", "tags": ["Master Inbox"], "parameters": [ { "name": "roomId", "in": "path", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "pageCursor", "schema": { "type": "string" } }, { "in": "query", "name": "pageSize", "schema": { "type": "string" } }, { "in": "query", "name": "search", "schema": { "type": "string" } } ], "summary": "List chat room stories", "description": "Returns a paginated list of messages (stories) for a specific chat room. Supports cursor-based pagination and optional text search." }, "post": { "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "storyId": { "type": "string", "description": "Upwork story ID." }, "userId": { "type": ["string", "null"], "description": "Upwork user ID of the sender." }, "userName": { "type": "string", "description": "Display name of the sender." }, "userPhotoUrl": { "type": "string", "description": "Avatar URL of the sender." }, "message": { "type": "string", "description": "Message text content." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the message was sent (ISO-8601)." } }, "required": [ "storyId", "userId", "userName", "userPhotoUrl", "message", "createdAt" ] } }, "required": ["data"] } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" }, "instance": { "type": "string", "format": "uri" } }, "required": ["type", "title", "status", "detail", "instance"] } } } }, "403": { "description": "Access denied — addon required or freelancer not authorized", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" }, "instance": { "type": "string", "format": "uri" } }, "required": ["type", "title", "status", "detail", "instance"] } } } }, "404": { "description": "Room or freelancer not found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" }, "instance": { "type": "string", "format": "uri" } }, "required": ["type", "title", "status", "detail", "instance"] } } } } }, "operationId": "postV1Master-inboxRoomsByRoomIdStories", "tags": ["Master Inbox"], "parameters": [ { "name": "roomId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Plain text message to send.", "example": "Hi, I'd like to discuss the project details." }, "freelancerUid": { "type": "string", "description": "UID of the freelancer whose OAuth credentials will be used to send the message.", "example": "1621293360163461120" } }, "required": ["message", "freelancerUid"] } } } }, "summary": "Send a message to a chat room", "description": "Sends a plain-text message to a specific chat room via the Upwork messaging API. Requires an authorized freelancer who is a participant in the room. The workspace must have an active Master Inbox addon subscription, trial, or feature flag." } } } }