openapi: 3.0.3
info:
  title: Signet API
  version: 2.4.0
  description: |
    Score an email address, phone number or IP address for signup and order
    fraud. Every check returns a `verdict` (`allow`, `review` or `block`), a
    `risk_score` from 0 to 1 and the named signals behind it.

    **Billing.** A check rejected by the free rules costs nothing. A check
    that passes them and goes through the deep layer (DNS deliverability and
    network reputation) costs 1 credit. Duplicates inside a batch are charged
    once. Requests that return an error are never charged.

    **Limits.** Checks per minute depend on the plan (300 on the trial; 60,
    300 or 1,200 on Starter, Professional and Scale; a batch counts one per
    item), 100 items per batch, 320 characters per value. Every account starts
    with a 7-day trial; after it ends calls return 402 `trial_ended`.

    **Errors** are JSON with a readable `error` and a stable `code`.

    Full guide: https://puresignet.com/docs/api
  contact:
    email: hello@puresignet.com
    url: https://puresignet.com

servers:
  - url: https://puresignet.com
    description: Production

tags:
  - name: Validation
    description: Score values and report outcomes
  - name: Account
    description: Balance, usage and key check

security:
  - ApiKeyAuth: []

paths:
  /v1/validate:
    post:
      tags: [Validation]
      summary: Score one value
      operationId: validate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateRequest'
            examples:
              email:
                summary: Email
                value: { input: "jane@company.com" }
              phone:
                summary: Phone
                value: { input: "+919812345678", type: "phone" }
              ip:
                summary: IP address
                value: { input: "8.8.8.8" }
      responses:
        '200':
          description: The verdict
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      credits_remaining:
                        type: integer
                        description: Balance after this call
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/InsufficientCredits' }
        '403': { $ref: '#/components/responses/Suspended' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /v1/validate/batch:
    post:
      tags: [Validation]
      summary: Score up to 100 values
      description: |
        Results come back in the order sent. A repeated value is charged once
        and returned with `cached: true`. The batch is all-or-nothing: if the
        balance cannot cover it, nothing is charged.
      operationId: validateBatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
            example:
              items: ["jane@company.com", "x@mailinator.com", "8.8.8.8"]
      responses:
        '200':
          description: One result per item, plus a summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/InsufficientCredits' }
        '403': { $ref: '#/components/responses/Suspended' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /v1/feedback:
    post:
      tags: [Validation]
      summary: Report how a value turned out
      description: |
        Free. Report a chargeback, fake account or returned order as `fraud`,
        or a confirmed good customer as `legit`. Each account counts as one
        vote per value; a new report replaces your earlier one.
      operationId: feedback
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedbackRequest'
            example: { input: "fraudster@example.com", outcome: "fraud" }
      responses:
        '200':
          description: Recorded
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  type: { type: string, enum: [email, phone, ip] }
                  outcome: { type: string, enum: [fraud, legit] }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '422':
          description: The value is not a well-formed email, phone number or IP
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /v1/credits:
    get:
      tags: [Account]
      summary: Current balance
      operationId: getCredits
      responses:
        '200':
          description: Balance
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance: { type: integer, example: 97 }
                  api_key: { type: string, description: First characters of the key, example: "ak_live_9f3c…" }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/usage:
    get:
      tags: [Account]
      summary: Totals and recent checks
      description: Inputs are stored masked, so this never returns a full email, phone number or IP.
      operationId: getUsage
      parameters:
        - name: limit
          in: query
          description: How many recent checks to return. 0 returns totals only.
          schema: { type: integer, minimum: 0, maximum: 1000, default: 50 }
      responses:
        '200':
          description: Usage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/test:
    post:
      tags: [Account]
      summary: Check that a key works
      description: Free. Returns the account the key belongs to.
      operationId: testKey
      responses:
        '200':
          description: The key is valid
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  message: { type: string }
                  account:
                    type: object
                    properties:
                      email: { type: string }
                      balance: { type: integer }
                  endpoints:
                    type: object
                    additionalProperties: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your key, `ak_live_` followed by 32 hexadecimal characters.

  responses:
    BadRequest:
      description: Something in the request body is missing or wrong (`bad_input`, `bad_type`, `bad_country`, `bad_live`, `bad_items`, `too_many_items`, `bad_outcome`, `bad_json`)
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Unauthorized:
      description: The key is missing, malformed or unknown (`invalid_api_key`)
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    InsufficientCredits:
      description: The balance cannot cover this request (`insufficient_credits`), the trial has ended (`trial_ended`), or there is no active plan (`no_plan`). Nothing was charged.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - type: object
                properties:
                  needed: { type: integer }
                  balance: { type: integer }
    Suspended:
      description: The account is paused (`account_suspended`)
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    RateLimited:
      description: Too many checks this minute (`rate_limited`)
      headers:
        Retry-After:
          description: Seconds to wait before retrying
          schema: { type: integer }
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }

  schemas:
    ValidateRequest:
      type: object
      required: [input]
      properties:
        input:
          type: string
          maxLength: 320
          description: The email address, phone number or IP address to check
        type:
          type: string
          enum: [email, phone, ip]
          description: Leave out to auto-detect
        country:
          type: string
          minLength: 2
          maxLength: 2
          description: Two-letter country code used to read phone numbers written without a "+"
          example: IN
        live:
          type: boolean
          description: |
            Ask for a live check: mailbox existence for emails (+1 credit),
            in-service status and carrier for phones (+2 credits). The extra
            credits are charged only when the source answers.

    BatchRequest:
      type: object
      required: [items]
      properties:
        items:
          type: array
          minItems: 1
          maxItems: 100
          items: { type: string, maxLength: 320 }
        type:
          type: string
          enum: [email, phone, ip]
          description: Applies one type to every item. Leave out to auto-detect each.
        country:
          type: string
          minLength: 2
          maxLength: 2
          description: Two-letter country code used for phone numbers written without a "+"
        live:
          type: boolean
          description: |
            Ask for a live check: mailbox existence for emails (+1 credit),
            in-service status and carrier for phones (+2 credits). The extra
            credits are charged only when the source answers.

    FeedbackRequest:
      type: object
      required: [input, outcome]
      properties:
        input: { type: string, maxLength: 320 }
        outcome: { type: string, enum: [fraud, legit] }
        type: { type: string, enum: [email, phone, ip] }

    Result:
      type: object
      properties:
        input: { type: string, description: What you sent }
        type: { type: string, enum: [email, phone, ip] }
        normalized: { type: string, description: Cleaned form of the input }
        valid:
          type: boolean
          description: Well-formed and risk score under 0.5
        verdict:
          type: string
          enum: [allow, review, block]
          description: |
            `allow` below 0.3, `review` from 0.3, `block` at 0.7 or for
            malformed input.
        risk_score: { type: number, minimum: 0, maximum: 1 }
        confidence: { type: number, minimum: 0, maximum: 1 }
        fraud_indicators:
          type: array
          items: { type: string }
          example: ["disposable_domain"]
        network:
          type: object
          nullable: true
          description: Counts from other merchants. Null for malformed input.
          properties:
            merchants_seen: { type: integer }
            merchants_flagged: { type: integer }
            fraud_reports: { type: integer }
            velocity_24h: { type: integer, description: Checks of this value in the last 24 hours }
        layer:
          type: string
          description: Starts with `local_` for the free rules; `deep_network` for the deep check
        credits_used: { type: integer, description: 0 or 1, plus 1 (email) or 2 (phone) when a live check answered }
        cached: { type: boolean, description: True for a repeated value inside a batch }
        response_time_ms: { type: integer }
        suggestion: { type: string, description: Emails only. The likely intended address. }
        free_provider: { type: boolean, description: Emails only. A consumer mailbox provider. }
        country: { type: string, description: Phones only. Two-letter country code., example: IN }
        line_type:
          type: string
          description: Phones only
          enum: [mobile, landline, landline_or_mobile, voip, toll_free, premium_rate, other]
        formatted: { type: string, description: Phones only. International format., example: "+91 98200 34571" }
        provider: { type: string, description: IPs only. Organisation that operates the network. }
        asn: { type: integer, description: IPs only. AS number of the network. }
        network_country: { type: string, description: IPs only. Where the network block is registered. }
        proxy_type: { type: string, enum: [vpn, tor, proxy], description: IPs only. Present when an anonymiser is detected. }
        live: { type: boolean, description: True when a live check answered for this item }
        domain_age_days: { type: integer, description: Emails on a business domain, when known. Days since the domain was registered. }
        mailbox: { type: string, enum: [deliverable, undeliverable, catch_all], description: Emails, live check only }
        line_status: { type: string, enum: [connected, absent, not_in_service], description: Phones, live check only }
        carrier: { type: string, description: Phones, live check only. Current network. }
        ported: { type: boolean, description: Phones, live check only }

    BatchResponse:
      type: object
      properties:
        results:
          type: array
          items: { $ref: '#/components/schemas/Result' }
        summary:
          type: object
          properties:
            total: { type: integer }
            valid: { type: integer }
            invalid: { type: integer }
            allow: { type: integer }
            review: { type: integer }
            block: { type: integer }
            credits_used: { type: integer }
        credits_remaining: { type: integer }

    Usage:
      type: object
      properties:
        email: { type: string }
        balance: { type: integer }
        total_validations: { type: integer }
        total_credits_used: { type: integer }
        recent_usage:
          type: array
          items:
            type: object
            properties:
              id: { type: integer }
              input: { type: string, description: Masked, example: "j***@company.com" }
              type: { type: string }
              valid: { type: boolean }
              credits: { type: integer }
              layer: { type: string }
              risk_score: { type: number, nullable: true }
              verdict: { type: string, enum: [allow, review, block] }
              indicators: { type: array, items: { type: string }, description: The signals behind the verdict }
              details:
                type: object
                description: |
                  Non-personal details of the check, when known: country, line_type,
                  carrier, ported, line_status (phones); provider, asn,
                  network_country, proxy_type (IPs); domain_age_days, and mailbox from a live check (emails).
                additionalProperties: true
              key_name: { type: string, nullable: true, description: Name of the API key that made the check }
              created_at: { type: string, format: date-time }
        message: { type: string }

    Error:
      type: object
      properties:
        error: { type: string, description: Human-readable message }
        code: { type: string, description: Stable machine-readable code }
        request_id: { type: string, description: Present on 500 responses. Quote it to support. }
