Sertifier Campaigns API

openapi: 3.0.3
info:
  title: Sertifier Credential Attributes Campaigns API
  description: 'The Sertifier Credential API lets backend systems and LMS/CRM integrations programmatically design, issue, verify, and manage verifiable digital credentials (certificates and badges) on the Sertifier platform. A credential is issued inside a Campaign that binds three things: a visual Design, a descriptive Detail, and an Email Template used to deliver the finished credential to a Recipient. Custom Attributes are merged into the design and email at issue time. All requests are sent to the base host with a private API key in the `secretKey` header and an `api-version` header. Most responses share a common envelope ({ message, hasError, validationErrors, data, content }). All dates are UTC. Designs are authored in the Sertifier web application; the API references and duplicates them.

    Endpoint paths, methods, the base host (https://b2b.sertifier.com), the `secretKey` / `api-version` headers, and the credential-issuance workflow are grounded in Sertifier''s public Apiary reference, help-center quickstart, and integration guides. Request and response bodies are minimally modeled where the public reference does not fully enumerate every field; those are marked with `x-modeled: true`.'
  version: '3.3'
  contact:
    name: Sertifier
    url: https://sertifier.com
    email: support@sertifier.com
  x-logo:
    url: https://kinlane-images.s3.amazonaws.com/shared/apis-json/apis-json-logo.jpg
servers:
- url: https://b2b.sertifier.com
  description: Sertifier Credential API (production)
security:
- secretKey: []
tags:
- name: Campaigns
  description: Containers that bind a Design, Detail, and Email Template and issue credentials.
paths:
  /campaign:
    post:
      operationId: createCampaign
      tags:
      - Campaigns
      summary: Create a campaign
      description: Creates a credential campaign, referencing a Design ID, a Detail ID, and an Email Template ID. Returns the created campaign including its campaignId, which is used to issue credentials.
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignCreate'
      responses:
        '200':
          description: The created campaign.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /campaign/{campaignId}:
    get:
      operationId: getCampaign
      tags:
      - Campaigns
      summary: Retrieve a campaign
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/CampaignId'
      responses:
        '200':
          description: The requested campaign.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: updateCampaign
      tags:
      - Campaigns
      summary: Update a campaign
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/CampaignId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignCreate'
      responses:
        '200':
          description: The updated campaign.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteCampaign
      tags:
      - Campaigns
      summary: Delete a campaign
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/CampaignId'
      responses:
        '200':
          description: The campaign was deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /campaign/search:
    post:
      operationId: searchCampaigns
      tags:
      - Campaigns
      summary: Search campaigns
      description: Returns a paginated list of campaigns matching the search filters.
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: A paginated list of campaigns.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /campaign/addCredentials:
    post:
      operationId: addCredentials
      tags:
      - Campaigns
      summary: Add / issue credentials to a campaign
      description: Issues one or more credentials into a campaign. Each credential references the campaignId and a recipient (name + email) plus optional custom attributes, external ID, issue date, and publish flags. Set quickPublish=true to publish immediately. Use an idempotency check on (enrolment ID + campaignId) if your source event can fire more than once. The response includes the permanent, verifiable credential URL.
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddCredentialsRequest'
      responses:
        '200':
          description: The issued credentials, including permanent credential URLs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /campaign/send:
    post:
      operationId: sendCampaign
      tags:
      - Campaigns
      summary: Publish / send a campaign's credentials
      description: Publishes the credentials in a campaign and sends delivery emails.
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                campaignId:
                  type: string
              required:
              - campaignId
      responses:
        '200':
          description: The campaign's credentials were published.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /campaign/schedule:
    post:
      operationId: scheduleCampaign
      tags:
      - Campaigns
      summary: Schedule credential distribution
      description: Schedules a campaign's credential distribution at a future UTC time.
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                campaignId:
                  type: string
                scheduleDate:
                  type: string
                  format: date-time
                  description: The UTC time at which to distribute credentials.
              required:
              - campaignId
              - scheduleDate
      responses:
        '200':
          description: The campaign distribution was scheduled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: The secretKey is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
  parameters:
    ApiVersion:
      name: api-version
      in: header
      required: true
      description: API version header. Current documented value is 3.3.
      schema:
        type: string
        default: '3.3'
    CampaignId:
      name: campaignId
      in: path
      required: true
      schema:
        type: string
  schemas:
    CampaignCreate:
      type: object
      properties:
        name:
          type: string
        designId:
          type: string
          description: The Design applied to credentials issued in this campaign.
        detailId:
          type: string
          description: The credential Detail printed on the credential.
        emailTemplateId:
          type: string
          description: The Email Template used to deliver the credential.
      required:
      - designId
      - emailTemplateId
    SearchRequest:
      type: object
      description: Paginated search request.
      x-modeled: true
      properties:
        page:
          type: integer
          default: 1
        pageSize:
          type: integer
          default: 20
        query:
          type: string
          nullable: true
    CredentialInput:
      type: object
      properties:
        name:
          type: string
          description: The recipient's full name.
        email:
          type: string
          format: email
          description: The recipient's email address.
        issueDate:
          type: string
          format: date
          description: The credential issue date (UTC).
        quickPublish:
          type: boolean
          description: Publish the credential immediately.
        dontSendEmail:
          type: boolean
          description: Suppress Sertifier's delivery email.
        externalId:
          type: string
          description: A reference ID from your own system, useful for idempotency.
        updateExistingCredentials:
          type: boolean
          description: Update a matching existing credential instead of creating a duplicate.
        attributes:
          type: array
          description: Custom attribute values merged into the design and email.
          items:
            type: object
            properties:
              id:
                type: string
              value:
                type: string
      required:
      - name
      - email
    AddCredentialsRequest:
      type: object
      properties:
        campaignId:
          type: string
          description: The campaign container to issue credentials into.
        credentials:
          type: array
          items:
            $ref: '#/components/schemas/CredentialInput'
      required:
      - campaignId
      - credentials
    Envelope:
      type: object
      description: Standard Sertifier response envelope.
      properties:
        message:
          type: string
          nullable: true
        hasError:
          type: boolean
        validationErrors:
          type: array
          items:
            type: string
        data:
          nullable: true
          description: The operation-specific payload (object or array).
        content:
          nullable: true
  securitySchemes:
    secretKey:
      type: apiKey
      in: header
      name: secretKey
      description: Private API key obtained from the Sertifier web application under Settings > API & Integrations (also referenced as Advanced > Integrations). Store it in a secrets vault; never embed it in client-side JavaScript.