samva-dev

samva-dev Custom Fields API

Custom field definitions for contact metadata

GitHub OpenAPI

Operations 4

GET /v1/custom-fields List custom fields #
POST /v1/custom-fields Create a custom field #
PATCH /v1/custom-fields/{id} Update a custom field #
DELETE /v1/custom-fields/{id} Delete a custom field #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/samva-dev/openapi/samva-dev-custom-fields-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/samva-dev/json-schema/samva-dev-email-domain-verification-schema.json
📊
JSONSchema
https://artifacts.apis.io/samva-dev/json-schema/samva-dev-contact-schema.json
📊
JSONSchema
https://artifacts.apis.io/samva-dev/json-schema/samva-dev-template-schema.json
📊
JSONSchema
https://artifacts.apis.io/samva-dev/json-schema/samva-dev-conversation-schema.json
📊
JSONSchema
https://artifacts.apis.io/samva-dev/json-schema/samva-dev-message-schema.json
📊
JSONSchema
https://artifacts.apis.io/samva-dev/json-schema/samva-dev-mailbox-message-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/samva-dev:samva-dev-custom-fields-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

samva-dev-custom-fields-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Samva Custom Fields API
  version: 1.0.0
  description: Samva is the email API for your app. Send transactional email in one typed call. Delivery events and customer replies come back as signed webhooks, and replies thread to the email they answer.
servers:
- url: https://api.samva.dev
security: []
tags:
- name: Custom Fields
  description: Custom field definitions for contact metadata
paths:
  /v1/custom-fields:
    get:
      tags:
      - Custom Fields
      operationId: customFields.list
      parameters: []
      security:
      - apiKey: []
      responses:
        '200':
          description: CustomFieldList
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldList'
        '401':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: ForbiddenError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '422':
          description: ValidationError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '500':
          description: InternalError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
        '504':
          description: GatewayTimeoutError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayTimeoutError'
      description: Returns every custom field definition for the organization in display order. An organization defines at most 100, so the list is never paged.
      summary: List custom fields
      x-samva-scope: contacts:read
    post:
      tags:
      - Custom Fields
      operationId: customFields.create
      parameters: []
      security:
      - apiKey: []
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    $ref: '#/components/schemas/CustomFieldDefinitionId'
                  organizationId:
                    $ref: '#/components/schemas/OrganizationId'
                  key:
                    type: string
                  label:
                    type: string
                  type:
                    type: string
                    enum:
                    - text
                    - number
                    - boolean
                    - date
                    - select
                  options:
                    anyOf:
                    - type: array
                      items:
                        type: string
                    - type: 'null'
                  defaultValue:
                    anyOf:
                    - type: string
                    - type: 'null'
                  isRequired:
                    type: boolean
                  sortOrder:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  createdAt:
                    type: string
                  updatedAt:
                    type: string
                required:
                - id
                - organizationId
                - key
                - label
                - type
                - options
                - defaultValue
                - isRequired
                - sortOrder
                - createdAt
                - updatedAt
                additionalProperties: false
        '401':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: ForbiddenError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '409':
          description: ConflictError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictError'
        '422':
          description: ValidationError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '500':
          description: InternalError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
        '504':
          description: GatewayTimeoutError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayTimeoutError'
      description: Creates a new custom field definition and returns it with a 201 status; the field key must be unique, and an organization defines at most 100.
      summary: Create a custom field
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                key:
                  type: string
                label:
                  type: string
                type:
                  type: string
                  enum:
                  - text
                  - number
                  - boolean
                  - date
                  - select
                options:
                  anyOf:
                  - type: array
                    items:
                      type: string
                  - type: 'null'
                defaultValue:
                  anyOf:
                  - type: string
                  - type: 'null'
                  - type: 'null'
                isRequired:
                  anyOf:
                  - type: boolean
                  - type: 'null'
                sortOrder:
                  anyOf:
                  - type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  - type: 'null'
              required:
              - key
              - label
              - type
              additionalProperties: false
        required: true
      x-samva-scope: contacts:create
  /v1/custom-fields/{id}:
    patch:
      tags:
      - Custom Fields
      operationId: customFields.update
      parameters:
      - name: id
        in: path
        schema:
          $ref: '#/components/schemas/CustomFieldDefinitionId'
        required: true
      security:
      - apiKey: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    $ref: '#/components/schemas/CustomFieldDefinitionId'
                  organizationId:
                    $ref: '#/components/schemas/OrganizationId'
                  key:
                    type: string
                  label:
                    type: string
                  type:
                    type: string
                    enum:
                    - text
                    - number
                    - boolean
                    - date
                    - select
                  options:
                    anyOf:
                    - type: array
                      items:
                        type: string
                    - type: 'null'
                  defaultValue:
                    anyOf:
                    - type: string
                    - type: 'null'
                  isRequired:
                    type: boolean
                  sortOrder:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  createdAt:
                    type: string
                  updatedAt:
                    type: string
                required:
                - id
                - organizationId
                - key
                - label
                - type
                - options
                - defaultValue
                - isRequired
                - sortOrder
                - createdAt
                - updatedAt
                additionalProperties: false
        '401':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: ForbiddenError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: ResourceNotFoundError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundError'
        '422':
          description: ValidationError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '500':
          description: InternalError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
        '504':
          description: GatewayTimeoutError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayTimeoutError'
      description: Updates an existing custom field definition and returns the updated field.
      summary: Update a custom field
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  anyOf:
                  - type: string
                  - type: 'null'
                options:
                  anyOf:
                  - type: array
                    items:
                      type: string
                  - type: 'null'
                defaultValue:
                  anyOf:
                  - type: string
                  - type: 'null'
                  - type: 'null'
                isRequired:
                  anyOf:
                  - type: boolean
                  - type: 'null'
                sortOrder:
                  anyOf:
                  - type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  - type: 'null'
              additionalProperties: false
        required: true
      x-samva-scope: contacts:update
    delete:
      tags:
      - Custom Fields
      operationId: customFields.remove
      parameters:
      - name: id
        in: path
        schema:
          $ref: '#/components/schemas/CustomFieldDefinitionId'
        required: true
      security:
      - apiKey: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                required:
                - success
                additionalProperties: false
        '401':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: ForbiddenError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: ResourceNotFoundError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundError'
        '422':
          description: ValidationError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '500':
          description: InternalError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
        '504':
          description: GatewayTimeoutError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayTimeoutError'
      description: Permanently deletes a custom field definition by its ID.
      summary: Delete a custom field
      x-samva-scope: contacts:delete
components:
  schemas:
    ValidationError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - ValidationError
        message:
          type: string
        fields:
          anyOf:
          - type: object
            additionalProperties:
              type: array
              items:
                type: string
          - type: 'null'
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - validation
      x-retryable: false
    CustomFieldDefinitionId:
      type: string
      pattern: ^cfield_[0-9a-hjkmnp-tv-z]{16,24}$
      x-samva-brand: CustomFieldDefinitionId
    ConflictError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - ConflictError
        message:
          type: string
        resource:
          type: string
        id:
          anyOf:
          - type: string
          - type: 'null'
      required:
      - _tag
      - message
      - resource
      additionalProperties: false
      x-category:
      - conflict
      x-retryable: false
    GatewayTimeoutError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - GatewayTimeoutError
        message:
          type: string
        retryAfterSeconds:
          type: number
      required:
      - _tag
      - message
      - retryAfterSeconds
      additionalProperties: false
      x-category:
      - transient
      x-retryable: true
    OrganizationId:
      type: string
      pattern: ^org_[0-9a-hjkmnp-tv-z]{16,24}$
      x-samva-brand: OrganizationId
    UnauthorizedError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - UnauthorizedError
        message:
          type: string
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - auth
      x-retryable: false
    ForbiddenError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - ForbiddenError
        message:
          type: string
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - auth
      x-retryable: false
    CustomFieldList:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              id:
                $ref: '#/components/schemas/CustomFieldDefinitionId'
              organizationId:
                $ref: '#/components/schemas/OrganizationId'
              key:
                type: string
              label:
                type: string
              type:
                type: string
                enum:
                - text
                - number
                - boolean
                - date
                - select
              options:
                anyOf:
                - type: array
                  items:
                    type: string
                - type: 'null'
              defaultValue:
                anyOf:
                - type: string
                - type: 'null'
              isRequired:
                type: boolean
              sortOrder:
                type: integer
                minimum: 0
                maximum: 9007199254740991
              createdAt:
                type: string
              updatedAt:
                type: string
            required:
            - id
            - organizationId
            - key
            - label
            - type
            - options
            - defaultValue
            - isRequired
            - sortOrder
            - createdAt
            - updatedAt
            additionalProperties: false
          maxItems: 100
      required:
      - items
      additionalProperties: false
    InternalError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - InternalError
        message:
          type: string
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - transient
      x-retryable: true
    ResourceNotFoundError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - ResourceNotFoundError
        resource:
          type: string
        id:
          type: string
        message:
          type: string
      required:
      - _tag
      - resource
      - id
      - message
      additionalProperties: false
      x-category:
      - notFound
      x-retryable: false
  securitySchemes:
    apiKey:
      type: apiKey
      name: x-api-key
      in: header