> ## Documentation Index > Fetch the complete documentation index at: https://docs.stardex.com/llms.txt > Use this file to discover all available pages before exploring further. # Create deal > Create a new deal record. Provide `client_linkedin_url` to automatically look up or create the client company when `client_id` is not known. ## OpenAPI ````yaml /api-reference/openapi-v1.json post /v1/deals openapi: 3.1.0 info: title: Stardex API (v1) version: 1.0.0 description: >- Stardex ATS API — manage candidates, jobs, companies, and recruiting workflows. servers: - url: https://api.stardex.ai description: Production API server security: - bearerAuth: [] tags: - name: Persons description: Manage person records — contacts, work history, and custom fields. - name: Jobs description: Manage job postings — pipeline stages, team members, and custom fields. - name: Candidates description: Manage candidate records and pipeline stage transitions. - name: Companies description: Browse and retrieve company records. - name: Lists description: Create, search, and retrieve saved person and company lists. - name: Person Activities description: Create and manage activity records (notes, emails, meetings) for persons. - name: Team Members description: List team members for use in search filters and assignments. - name: Custom Fields description: Retrieve custom field definitions and tag options for search filters. paths: /v1/deals: post: tags: - Deals summary: Create deal description: >- Create a new deal record. Provide `client_linkedin_url` to automatically look up or create the client company when `client_id` is not known. operationId: createDeal requestBody: content: application/json: schema: $ref: '#/components/schemas/DealCreateRequest' responses: '201': description: Deal created content: application/json: schema: $ref: '#/components/schemas/DealCreateResponse' example: success: true data: id: aaa11111-bbbb-cccc-dddd-eeeeeeee1111 name: Acme Corp Staffing Agreement amount: 150000 currency_code: USD compensation: 750000 compensation_currency_code: USD pricing_rate: 20 win_probability: 75 deal_status_id: ccc33333-dddd-eeee-ffff-000000003333 client_id: bbb22222-cccc-dddd-eeee-ffffffff2222 job_ids: - eee55555-ffff-0000-1111-222222225555 owner_ids: - ddd44444-eeee-ffff-0000-111111114444 client_contact_ids: - ab12cd34-ef56-7890-ab12-cd34ef567890 open_date: '2024-01-15' created_at: '2024-01-15T10:00:00Z' '400': description: Validation error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '404': description: Resource not found content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error components: schemas: DealCreateRequest: type: object properties: name: type: string minLength: 1 description: Deal name (required). client_id: type: string format: uuid description: Client company UUID. client_linkedin_url: type: string format: uri description: >- Client company LinkedIn URL. Used to look up or create the client company if client_id is not provided. amount: type: number description: Deal amount — the fee the firm invoices the client. currency_code: type: string minLength: 3 maxLength: 3 description: >- ISO 4217 currency code (e.g. USD, EUR, GBP). Defaults to the organization setting or USD. compensation: type: number minimum: 0 description: Candidate's expected total annual compensation. compensation_currency_code: type: string minLength: 3 maxLength: 3 description: >- ISO 4217 currency code for compensation. Defaults to currency_code (or the organization default / USD). pricing_rate: type: number minimum: 0 maximum: 100 description: Recruitment fee percentage (0–100). win_probability: type: number minimum: 0 maximum: 100 description: Win probability (0–100). deal_status_id: type: string format: uuid description: Deal status UUID. Use List deal statuses endpoint to get the UUID. description: type: string description: Description. closed_date: type: string description: ISO 8601 expected or actual close date. open_date: type: string format: date description: >- Deal opening date (YYYY-MM-DD). Defaults to the deal's creation date. job_ids: type: array items: type: string format: uuid description: >- Job UUIDs to link to this deal. Creates entries in the deal_jobs table. referred_by: type: string format: uuid description: Person UUID of the referrer. owner_ids: type: array items: type: string format: uuid description: >- Team member UUIDs to assign as deal owners. If omitted, the caller is auto-assigned when authenticated as a team member. client_contact_ids: type: array items: type: string format: uuid description: >- Client contact UUIDs to attach as deal contacts. Get IDs from a client company page or by creating contacts via POST /v1/client-contacts. Each contact must belong to this team. When omitted, the deal is created with no contacts attached. custom_fields: type: array items: type: object properties: attribute_id: type: string format: uuid description: >- Custom attribute definition UUID. Get from GET /v1/custom-fields/deals. value: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: 'null' description: >- For scalar types: the value to set, or null to clear. For single-select: pass the tag NAME or the tag option UUID from GET /v1/custom-fields/deals. add_values: type: array items: type: string description: >- Tags to add for multi-select fields. Pass tag NAMES or tag option UUIDs. remove_values: type: array items: type: string description: >- Tags to remove for multi-select fields. Pass tag NAMES or tag option UUIDs. add_team_member_ids: type: array items: type: string format: uuid description: Team member UUIDs to add for multi-team-member fields. remove_team_member_ids: type: array items: type: string format: uuid description: Team member UUIDs to remove for multi-team-member fields. clear_all: type: boolean description: >- When true, removes all values for this attribute before applying adds. required: - attribute_id description: Custom field values to set on creation. required: - name DealCreateResponse: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/DealCreateResponseData' required: - success - data DealCreateResponseData: type: object properties: id: type: string format: uuid description: Created deal UUID. name: type: string description: Deal name. amount: type: - number - 'null' description: Deal amount. currency_code: type: string description: ISO 4217 currency code. compensation: type: - number - 'null' description: Candidate's expected total annual compensation. compensation_currency_code: type: string description: ISO 4217 currency code for compensation. pricing_rate: type: - number - 'null' description: Recruitment fee percentage (0–100). win_probability: type: - number - 'null' description: Win probability. deal_status_id: type: - string - 'null' format: uuid description: Deal status UUID. client_id: type: - string - 'null' format: uuid description: Client company UUID. job_ids: type: array items: type: string format: uuid description: UUIDs of jobs linked to this deal. owner_ids: type: array items: type: string format: uuid description: Team member UUIDs assigned as deal owners. client_contact_ids: type: array items: type: string format: uuid description: Client contact UUIDs attached to this deal as deal contacts. open_date: type: string format: date description: Date the deal was opened (YYYY-MM-DD). created_at: type: - string - 'null' description: ISO 8601 creation timestamp. required: - id - name - amount - currency_code - compensation - compensation_currency_code - pricing_rate - win_probability - deal_status_id - client_id - job_ids - owner_ids - client_contact_ids - open_date - created_at securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ````