GoFundMe Magic Link API

openapi: 3.2.0
info:
  title: GoFundMe Pro Magic Link API
  description: 'GoFundMe Pro API


    Welcome to the GoFundMe Pro API (2.0.0), a powerful toolset that empowers innovative and creative minds to engineer the world for good.'
  version: 2.0.0
servers:
- url: https://pro.gofundme.com/api/2.0
security:
- OAuth2Application: []
- OAuth2Member: []
tags:
- name: Magic Link
  description: MagicLink
paths:
  /scoped-magic-link/batch:
    post:
      tags:
      - Magic Link
      summary: Create an async, mint-only batch of scoped magic links (internal)
      description: 'Create a new magic-link batch (async, mint-only).


        Dispatches synchronously so the controller can return the batch_id and

        acceptance summary immediately (202 Accepted); the actual link-minting is

        handled by the async orchestrator dispatched inside CreateMagicLinkBatch.


        App-token-only: privateEndpoint blocks external apps, and

        assertAppTokenOnly() additionally rejects internal tokens that carry

        member context. A batch can span multiple orgs and is triggered

        service-to-service (the Admin bulk-generate flow) — there is no single

        member to act on behalf of, and no per-member resource to authorize

        against. Confirmed with the consuming squad (Admin): calls carry an app

        token, never a member-scoped token. If member-scoped access is ever

        added, re-check per-row authorization in MintScopedMagicLinkJob

        (security-patterns.md, IDOR + authorize-on-mutation rules).'
      operationId: a8ae5c40769c7673b17b5abbc5e48ab7
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - action_scope
              - idempotency_key
              - requests
              properties:
                action_scope:
                  type: string
                  example: recurring_plan_edit
                idempotency_key:
                  type: string
                  example: admin-batch-2026-07-08-abc123
                requests:
                  type: array
                  items:
                    required:
                    - organization_id
                    - recurring_donation_plan_id
                    properties:
                      organization_id:
                        type: string
                        example: '29720'
                      recurring_donation_plan_id:
                        type: string
                        example: '137583'
                      expires_at:
                        type: string
                        format: date-time
                      amounts:
                        type: array
                        items:
                          type: integer
                    type: object
              type: object
      responses:
        '202':
          description: Batch accepted; minting proceeds asynchronously. Poll the Location header (GET status) for progress.
          content:
            application/json:
              schema:
                required:
                - batch_id
                - total
                - accepted
                - rejected
                properties:
                  batch_id:
                    type: string
                    example: '4471'
                  total:
                    type: integer
                    example: 3
                  accepted:
                    type: integer
                    example: 2
                  rejected:
                    type: array
                    items:
                      type: object
                type: object
        '400':
          description: 'Validation failed: bad action_scope, empty or oversized requests, or missing idempotency_key.'
        '403':
          description: Caller is an external app, or an internal app carrying member context (application tokens only).
  /scoped-magic-link/batch/{batch}:
    get:
      tags:
      - Magic Link
      summary: Return the rollup status for a magic-link batch (internal)
      description: 'Return the rollup status for a batch.


        Unscoped findOrFail is intentional: privateEndpoint + app-token-only gate

        the route and the id is the batch''s own surrogate key (not a tenant

        resource), so there is no cross-org IDOR surface.'
      operationId: c68f6111a6e1841596da2c5a55369411
      parameters:
      - name: batch
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Batch status rollup.
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: integer
                    example: 4471
                  organization_id:
                    type: string
                    example: '29720'
                  action_scope:
                    type: string
                    example: recurring_plan_edit
                  status:
                    type: string
                    example: completed
                  total_count:
                    type: integer
                    example: 100
                  completed_count:
                    type: integer
                    example: 98
                  failed_count:
                    type: integer
                    example: 2
                  progress_percentage:
                    type: integer
                    example: 100
                  is_complete:
                    type: boolean
                    example: true
                  is_processing:
                    type: boolean
                    example: false
                  started_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
                  completed_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
                  error_message:
                    type:
                    - string
                    - 'null'
                type: object
        '403':
          description: Caller is an external app, or an internal app carrying member context (application tokens only).
        '404':
          description: No batch exists with this id.
components:
  securitySchemes:
    OAuth2Application:
      type: oauth2
      description: OAuth bearer token for client application
      flows:
        clientCredentials:
          tokenUrl: /oauth2/auth
          refreshUrl: /oauth2/auth
          scopes:
            read: Read access
            write: Write access
    OAuth2Member:
      type: oauth2
      description: OAuth bearer token for client application with additional member context
      flows:
        password:
          tokenUrl: /oauth2/auth
          refreshUrl: /oauth2/auth
          scopes:
            read: Read access
            write: Write access