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

# Find-or-create person / org / deal in Pipedrive

> WP calls this endpoint for four lifecycle events. The DO Function
uses `email` as the primary lookup key for the person. When stored
Pipedrive IDs are available (`pipedrive_ids`), they are passed so
the function can update existing records directly.

**Event: demo_signup**
A public visitor signs up to try a demo sage. No WP user is created.
No `org_fields`, no `deal_fields`, no `pipedrive_ids`.

**Event: trial_created**
A council_admin completes Stripe checkout for a $299 I-SKU trial.
`council_name`, `org_fields`, and `deal_fields` are included.

**Event: paid_created**
A council_admin is created for a directly-provisioned paid account.
Same shape as trial_created with `customer_type: paid`.

**Event: user_added**
A team member is added to an existing council by an admin.
`council_name` and `org_fields.wp_council_id` are included.
`org_fields.wp_admin_email` and `deal_fields` are omitted.
Stored `org_id` and `deal_id` are passed (no `contact_id` since
the new user has no stored PD ID yet).




## OpenAPI

````yaml /openapi/private/specs/services/services-integrations.yml post /account-created
openapi: 3.1.0
info:
  title: SageScreen — Intake & Pipedrive Integrations
  version: 1.0.0
servers:
  - url: https://{domain}/wp-json/sagescreen/v1
    description: WordPress REST API
    variables:
      domain:
        default: sagescreen.app
security: []
tags:
  - name: Intake
    description: Sales intake item endpoints
  - name: Account Created
    description: |
      Find-or-create person, org, and deal in Pipedrive.
      Fired for four WP events:
      - Demo signup (candidate, no WP user)
      - Trial account created (council_admin, new council)
      - Paid account created (council_admin, new council)
      - Council user added (any role added to existing council)
  - name: Quote Sync
    description: |
      Advance the Pipedrive deal stage.
      Fired for two WP events:
      - Demo completed (candidate views results for first time)
      - Trial complete (council upgrades from trial to paid)
paths:
  /account-created:
    post:
      tags:
        - Account Created
      summary: Find-or-create person / org / deal in Pipedrive
      description: |
        WP calls this endpoint for four lifecycle events. The DO Function
        uses `email` as the primary lookup key for the person. When stored
        Pipedrive IDs are available (`pipedrive_ids`), they are passed so
        the function can update existing records directly.

        **Event: demo_signup**
        A public visitor signs up to try a demo sage. No WP user is created.
        No `org_fields`, no `deal_fields`, no `pipedrive_ids`.

        **Event: trial_created**
        A council_admin completes Stripe checkout for a $299 I-SKU trial.
        `council_name`, `org_fields`, and `deal_fields` are included.

        **Event: paid_created**
        A council_admin is created for a directly-provisioned paid account.
        Same shape as trial_created with `customer_type: paid`.

        **Event: user_added**
        A team member is added to an existing council by an admin.
        `council_name` and `org_fields.wp_council_id` are included.
        `org_fields.wp_admin_email` and `deal_fields` are omitted.
        Stored `org_id` and `deal_id` are passed (no `contact_id` since
        the new user has no stored PD ID yet).
      operationId: accountCreated
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountCreatedRequest'
            examples:
              demoSignup:
                summary: demo_signup — candidate tries a demo sage
                value:
                  email: john@example.com
                  first_name: John
                  last_name: Doe
                  phone: 555-1234
                  council_name: ACME Corp
                  customer_type: demo
                  person_fields:
                    wp_product: demo
              trialCreated:
                summary: trial_created — new council admin starts trial
                value:
                  email: admin@acme.com
                  first_name: Jane
                  last_name: Smith
                  phone: 555-9876
                  council_name: ACME Corp
                  customer_type: trial
                  person_fields:
                    wp_product: trial
                    wp_council_role: council_admin
                    wp_signup_source: linkedin
                  org_fields:
                    wp_council_id: c9d8e7f6-5a4b-3c2d-1e0f-a1b2c3d4e5f6
                    wp_admin_email: admin@acme.com
                  deal_fields:
                    wp_deal_type: trial
              paidCreated:
                summary: paid_created — new council admin on paid account
                value:
                  email: admin@bigco.com
                  first_name: Carlos
                  last_name: Rivera
                  phone: ''
                  council_name: BigCo LLC
                  customer_type: paid
                  person_fields:
                    wp_product: paid
                    wp_council_role: council_admin
                  org_fields:
                    wp_council_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    wp_admin_email: admin@bigco.com
                  deal_fields:
                    wp_deal_type: paid
              userAdded:
                summary: user_added — team member added to existing council
                value:
                  email: member@acme.com
                  first_name: Sara
                  last_name: Lee
                  phone: 555-4321
                  council_name: ACME Corp
                  customer_type: trial
                  person_fields:
                    wp_product: trial
                    wp_council_role: council_member
                  org_fields:
                    wp_council_id: c9d8e7f6-5a4b-3c2d-1e0f-a1b2c3d4e5f6
                  pipedrive_ids:
                    org_id: 4001
                    deal_id: 5001
      responses:
        '200':
          description: Sync result with Pipedrive record IDs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountCreatedResponse'
              examples:
                success:
                  summary: Person, org, and deal resolved
                  value:
                    ok: true
                    pd_contact_id: 1234
                    pd_org_id: 4001
                    pd_deal_id: 5001
                    contact_created: true
                    org_created: false
                    deal_created: false
                authFailure:
                  summary: Bad or missing secret
                  value:
                    ok: false
                    error: Unauthorized
      security:
        - doFunctionSecret: []
components:
  schemas:
    AccountCreatedRequest:
      type: object
      required:
        - email
        - first_name
        - last_name
        - customer_type
        - person_fields
      properties:
        email:
          type: string
          format: email
          description: Primary lookup key for the Pipedrive person record
          examples:
            - john@example.com
        first_name:
          type: string
          examples:
            - John
        last_name:
          type: string
          examples:
            - Doe
        phone:
          type: string
          description: Candidate or user phone number. Send whatever is available.
          examples:
            - 555-1234
        council_name:
          type: string
          description: >
            Display name of the council / company. For demo signups, this is

            the `company` field from the signup form. For council accounts,

            this is the council post title. For user_added, it is
            `get_the_title`

            of the council post.
          examples:
            - ACME Corp
        customer_type:
          type: string
          enum:
            - demo
            - trial
            - paid
          description: SageScreen product tier for this event
          examples:
            - trial
        person_fields:
          $ref: '#/components/schemas/PersonFields'
        org_fields:
          $ref: '#/components/schemas/OrgFields'
          description: |
            Included for trial_created, paid_created, and user_added.
            Omitted for demo_signup (no council relationship).
        deal_fields:
          $ref: '#/components/schemas/DealFields'
          description: |
            Included for trial_created and paid_created (wp_deal_type only).
            Omitted for demo_signup and user_added.
        pipedrive_ids:
          $ref: '#/components/schemas/StoredPipedriveIds'
          description: |
            Included only when stored IDs exist in WP meta. On first sync
            for a new contact/council this field is absent entirely.
    AccountCreatedResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: |
            true on success. An auth failure returns ok: false with no IDs.
            WP checks `ok === true` AND the presence of `pd_contact_id`
            before persisting any IDs — a bare `{"ok": true}` is treated
            as a no-op (no IDs to store).
          examples:
            - true
        pd_contact_id:
          type: integer
          description: >
            Pipedrive person ID. WP persists to
            `user_meta.pipedrive_contact_id`.

            Absent on demo signups (no WP user to attach meta to — WP ignores
            it).
          examples:
            - 1234
        pd_org_id:
          type: integer
          description: |
            Pipedrive org ID. WP persists to `post_meta.pipedrive_company_id`
            on the `ss_council` post.
          examples:
            - 4001
        pd_deal_id:
          type: integer
          description: |
            Pipedrive deal ID. WP persists to `post_meta.pipedrive_deal_id`
            on the `ss_council` post.
          examples:
            - 5001
        contact_created:
          type: boolean
          description: true if the person record was newly created (vs updated)
          examples:
            - true
        org_created:
          type: boolean
          description: true if the org record was newly created
          examples:
            - false
        deal_created:
          type: boolean
          description: true if the deal record was newly created
          examples:
            - false
        error:
          type: string
          description: Human-readable error when ok is false
          examples:
            - Unauthorized
    PersonFields:
      type: object
      description: |
        Custom Pipedrive person fields set on the contact record.
        Only fields with a value are sent.
      properties:
        wp_product:
          type: string
          enum:
            - demo
            - trial
            - paid
          description: SageScreen product the contact is associated with
          examples:
            - trial
        wp_council_role:
          type: string
          enum:
            - council_admin
            - council_power_user
            - council_member
            - member
          description: >-
            WP role slug for this user within their council. Omitted for demo
            signups.
          examples:
            - council_admin
        wp_signup_source:
          type: string
          description: |
            Value of `wp_signup_source` user meta. Only included if the meta
            key is set (not present for demo signups — no WP user exists).
          examples:
            - linkedin
    OrgFields:
      type: object
      description: Custom Pipedrive org fields set on the organization record.
      properties:
        wp_council_id:
          type: string
          format: uuid
          description: Council UUID from WP (`council_id` post meta on `ss_council`)
          examples:
            - c9d8e7f6-5a4b-3c2d-1e0f-a1b2c3d4e5f6
        wp_admin_email:
          type: string
          format: email
          description: >
            Council admin email. Included on new council creation
            (trial_created,

            paid_created). Omitted when adding a team member to an existing
            council.
          examples:
            - admin@acme.com
    DealFields:
      type: object
      description: Custom Pipedrive deal fields.
      properties:
        wp_deal_type:
          type: string
          enum:
            - trial
            - paid
          description: |
            Deal type for new council accounts. Omitted for demo signups and
            user_added events (deal already exists for the council).
          examples:
            - trial
        wp_website:
          type: string
          format: uri
          description: |
            Website URL from demo user's signup form. Sent on demo_complete
            if the `url` field was provided during demo signup.
          examples:
            - https://acme.com
    StoredPipedriveIds:
      type: object
      description: >
        Pipedrive record IDs stored in WP meta from a prior sync response.

        Passed back on subsequent calls so the DO Function updates existing

        records rather than creating duplicates. Any absent ID is simply
        omitted.
      properties:
        contact_id:
          type: integer
          description: Pipedrive person ID (`user_meta.pipedrive_contact_id`)
          examples:
            - 1234
        org_id:
          type: integer
          description: Pipedrive org ID (`post_meta.pipedrive_company_id` on `ss_council`)
          examples:
            - 4001
        deal_id:
          type: integer
          description: Pipedrive deal ID (`post_meta.pipedrive_deal_id` on `ss_council`)
          examples:
            - 5001
  securitySchemes:
    doFunctionSecret:
      type: apiKey
      in: query
      name: k
      description: |
        Secret key appended by WP as `?k=<secret>`.
        Account-created uses `ss_pipedrive_sync_secret`.
        Quote-sync uses `ss_pipedrive_quote_sync_secret`.

````