> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revyops.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Save Opportunity Mappings

> Maps CRM stages or lost reasons onto the standard values for one CRM. Only the values you send change; null removes a mapping. Stored deals are updated before the call returns.

Maps one CRM's deal stages or lost reasons onto the standard values that fill **Normalized Stage** and **Lost Reason Category**. Take the source values from [List Opportunity Mappings](/api-reference/opportunities/list-mappings); they match after trimming spaces. Only the values you send change, and `null` removes a mapping. Stored deals are updated before the call returns, and the response is the same listing for that CRM plus `deals_updated`.

```json theme={null}
{
  "kind": "stage",
  "origin": "closecrm",
  "mappings": {"Qualified": "qualification", "Proposal Sent": "proposal", "Demo Done": null}
}
```

`stage` takes `qualification`, `discovery`, `evaluation`, `proposal` or `negotiation`. Won and lost deals are `closed` automatically, so `closed` is not accepted here. `lost_reason` takes `price`, `product_gap`, `timing`, `competitor`, `no_decision`, `disqualified` or `other`.


## OpenAPI

````yaml POST /public/opportunities/mappings
openapi: 3.0.3
info:
  title: RevyOps API
  version: 1.0.0
servers:
  - url: https://app.revyops.com/api
security:
  - ApiKeyAuth: []
paths:
  /public/opportunities/mappings:
    post:
      tags:
        - public
      description: >-
        Maps CRM stages or lost reasons onto the standard values for one CRM.
        Only the values you send change; null removes a mapping. Stored deals
        are updated before the call returns.
      operationId: Save opportunity mappings
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpportunityMappingsRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/OpportunityMappingsRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OpportunityMappingsRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpportunityMappingsUpdated'
          description: ''
        '400':
          description: >-
            Bad Request. Unknown kind or origin, or a standard value outside
            canonical_options.
components:
  schemas:
    OpportunityMappingsRequest:
      type: object
      properties:
        kind:
          $ref: '#/components/schemas/KindEnum'
        origin:
          $ref: '#/components/schemas/OriginEnum'
        mappings:
          type: object
          additionalProperties:
            type: string
            nullable: true
          description: >-
            CRM value to standard value, e.g. {"Proposal Sent": "proposal"}.
            null removes a mapping.
      required:
        - kind
        - mappings
        - origin
    OpportunityMappingsUpdated:
      type: object
      properties:
        canonical_options:
          $ref: '#/components/schemas/OpportunityMappingCanonicalOptions'
        values:
          type: array
          items:
            $ref: '#/components/schemas/OpportunityMappingValue'
        deals_updated:
          type: integer
      required:
        - canonical_options
        - deals_updated
        - values
    KindEnum:
      enum:
        - stage
        - lost_reason
      type: string
      description: |-
        * `stage` - stage
        * `lost_reason` - lost_reason
    OriginEnum:
      enum:
        - closecrm
        - hubspot
      type: string
      description: |-
        * `closecrm` - closecrm
        * `hubspot` - hubspot
    OpportunityMappingCanonicalOptions:
      type: object
      properties:
        stage:
          type: array
          items:
            type: string
        lost_reason:
          type: array
          items:
            type: string
      required:
        - lost_reason
        - stage
    OpportunityMappingValue:
      type: object
      properties:
        origin:
          $ref: '#/components/schemas/OriginEnum'
        kind:
          $ref: '#/components/schemas/KindEnum'
        source_value:
          type: string
          description: The stage or lost reason exactly as the CRM sends it, trimmed.
        deals:
          type: integer
          description: Deals carrying this value now. 0 means a mapping no deal uses yet.
        canonical_value:
          type: string
          nullable: true
          description: The standard value it maps to. null is unmapped.
      required:
        - canonical_value
        - deals
        - kind
        - origin
        - source_value
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.