Service Definition Guide

The service definition endpoint /getServiceDefinition is one of three required endpoints in your OpenAPI specification. It declares your service's capabilities, data requirements, and configuration options.

Prerequisites

Before implementing this endpoint, ensure you:

1. Create your OpenAPI Spec with the required components.
2. Define at least one security scheme (apiKey, oauth2, or basicAuth) .
3. Include the three required endpoints in your spec .

GET /getServiceDefinition

Response: ServiceDefinition object (application/json)

Your service must support exactly ONE entity type:

• lead (Lead/Person)

  • Requires fields in payload definitions
  • Use for: lead enrichment, scoring, qualification

• account (Account)

  • Requires accountFields in payload definitions
  • Use for: account enrichment, firmographic data, ABM scoring

• accountPerson (Leads within Accounts)

  • Requires BOTH fields AND accountFields
  • Use for: buying group analysis, relationship scoring, multi-touch attribution

Authentication & Security

Your OpenAPI specification must define one of the following security schemes:

API Key Authentication

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header          # or 'query'
      name: X-API-Key     # customize header/query param name
      description: API Key authentication

security:
  - apiKey: []

OAuth 2.0

components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth2 authentication
      flows:
        authorizationCode:
          authorizationUrl: https://your-service.com/oauth/authorize
          tokenUrl: https://your-service.com/oauth/token
          refreshUrl: https://your-service.com/oauth/refreshToken
          scopes: {}
        # OR clientCredentials:
        clientCredentials:
          tokenUrl: https://your-service.com/oauth/token
          scopes: {}

security:
  - oauth2: []

HTTP Basic Authentication

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication

security:
  - basicAuth: []

• Adobe only allows one security scheme defined in your root-level security array.
• The security scheme must be defined in both components.securitySchemes and in the root-level security array.

Invocation Payload Definition

The invocation payload defines what data your service needs from Adobe.

invocationPayloadDef:
  globalAttributes:
    - serviceAttribute: apiKey
      dataType: string
      required: true
      description: API key for service authentication
  flowAttributes:
    - serviceAttribute: campaignId
      dataType: string
      required: false
      description: Campaign identifier
  fields:  # Required for 'lead' and 'accountPerson'
    - serviceAttribute: email
      dataType: email
      required: true
      description: Person email address
  accountFields:  # Required for 'account' and 'accountPerson'
    - serviceAttribute: accountName
      dataType: string
      required: true
      description: Account name
  headers:
    - headerName: X-Custom-Header
      defaultValue: default-value
      description: Custom header for API calls
  journeyContext: true  # Include journey metadata
  subscriptionContext: true  # Include subscription metadata
  accessorsMetadata:  # Required when enableSplitPaths: true
    - accessorName: score
      dataType: integer
      description: Computed score for routing

Field definition properties

Attribute definition properties

For globalAttributes and flowAttributes, each attribute must include:

Callback Payload Definition

Defines what data your service can update in Adobe systems.

callbackPayloadDef:
  fields:  # Optional - only include if your service updates person attributes
    - serviceAttribute: email
      dataType: email
      required: false
      description: Updated email address
    - serviceAttribute: leadScore
      dataType: integer
      required: false
      description: Computed lead score
  accountFields:  # Optional - only include if your service updates account attributes
    - serviceAttribute: revenue
      dataType: integer
      required: false
      description: Updated revenue
  attributes:
    - serviceAttribute: processingStatus
      dataType: string
      description: Processing status

Split Path Configuration

When enableSplitPaths: true, you must define accessorsMetadata in invocationPayloadDef.

Accessors are named values that can be used in path conditions.

accessorsMetadata:
  - accessorName: enrichmentScore
    dataType: integer
    description: Enrichment score for routing
    constraints:
      minValue: 0
      maxValue: 100
  - accessorName: treatmentId
    dataType: string
    description: Recommended treatment
    constraints:
      allowedValues: ["premium", "standard", "basic"]

Administrators can create path conditions using these accessors:

• my.enrichmentScore >= 80
• my.treatmentId == 'premium'

Your service returns accessor values in callbacks:

{
  "accessorValues": {
    "enrichmentScore": 92,
    "treatmentId": "premium"
  }
}

Example

apiName: "dataEnrichmentService"
i18n:
  en_US:
    name: "Data Enrichment Service"
    description: "Enriches lead and account data with third-party intelligence"
description: "Enriches lead and account data with third-party intelligence"
primaryAttribute: "email"
supportedEntityType: lead
enableSplitPaths: true
timeout: 120

invocationPayloadDef:
  globalAttributes:
    - apiName: apiKey
      dataType: string
      required: true
      i18n:
        en_US:
          displayName: "API Key"
          description: "Service API key"
    - apiName: region
      dataType: string
      required: false
      i18n:
        en_US:
          displayName: "Data Region"
          description: "Data region (US, EU, APAC)"
  flowAttributes:
    - apiName: enrichmentType
      dataType: string
      required: true
      i18n:
        en_US:
          displayName: "Enrichment Type"
          description: "Type of enrichment to perform"
  fields:
    - serviceAttribute: email
      dataType: email
      required: true
      description: Person email address
    - serviceAttribute: company
      dataType: string
      required: false
      description: Company name
    - serviceAttribute: title
      dataType: string
      required: false
      description: Job title
  headers:
    - headerName: X-Tenant-ID
      description: Tenant identifier
  journeyContext: true
  subscriptionContext: true
  accessorsMetadata:
    - accessorName: enrichmentScore
      dataType: integer
      description: Data quality score (0-100)
      constraints:
        minValue: 0
        maxValue: 100
    - accessorName: dataQuality
      dataType: string
      description: Data quality level
      constraints:
        allowedValues: ["high", "medium", "low"]

callbackPayloadDef:
  fields:
    - serviceAttribute: email
      dataType: email
      description: Verified email address
    - serviceAttribute: mobilePhone
      dataType: string
      description: Enriched mobile phone
    - serviceAttribute: linkedInUrl
      dataType: url
      description: LinkedIn profile URL
    - serviceAttribute: seniority
      dataType: string
      description: Job seniority level
  attributes:
    - serviceAttribute: enrichmentStatus
      dataType: string
      description: Enrichment processing status
    - serviceAttribute: enrichmentDate
      dataType: datetime
      description: When enrichment was performed

Validation

Adobe validates your service definition with:

1. Schema validation: Ensures that all required fields are present.

2. Entity type validation: Checks conditional field requirements.

   • lead requires fields in at least one of the payload defs
   • account requires accountFields in at least one of the payload defs
   • accountPerson requires accountPersonRelationships in invocation payload; optionally supports fields and/or accountFields for attribute updates

3. Split path validation: When enableSplitPaths: true, requires accessorsMetadata.

4. Data type validation: Ensures that data types are valid.

Best Practices

• Use descriptive names: Make serviceAttribute names clear and intuitive.
• Provide good descriptions: Help admins understand field purposes.
• Mark fields required carefully: Only require truly necessary fields.
• Use appropriate data types: Leverage specific types (email, url) for validation.
• Define clear accessors: When using split paths, provide meaningful accessor names.
• Version your service: Update serviceVersion when making changes.
• Document constraints: Use constraints to define valid value ranges.