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:

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

`GET /getServiceDefinition`

Response: ServiceDefinition object (application/json)

Property

Type

Description

apiName

string

Unique identifier for your service

i18n

object

Internationalization strings (at minimum en_US with name and description)

description

string

Human-readable service description

supportedEntityType

string

Entity type: lead, account, or accountPerson

primaryAttribute

string

API name of the primary attribute from flow attributes that describes the main asset

invocationPayloadDef

object

Defines data needed by your service

callbackPayloadDef

object

Defines data your service can update

enableSplitPaths

boolean

Whether split path decisioning is enabled (required, set to true or false)

timeout

integer

Optional. Callback timeout in minutes (max: 240)

Your service must support exactly ONE entity type:

lead (Lead/Person)
- Requires fields in invocationPayloadDef
- Use for: lead enrichment, scoring, qualification
account (Account)
- Requires accountFields in invocationPayloadDef
- Use for: account enrichment, firmographic data, ABM scoring
accountPerson (Leads within Accounts)
- Requires at least one of fields or accountFields in invocationPayloadDef
- 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:
    - apiName: apiKey
      i18n:
        en_US:
          displayName: "API Key"
          description: "API key for service authentication"
      dataType: string
      required: true
  flowAttributes:
    - apiName: campaignId
      i18n:
        en_US:
          displayName: "Campaign ID"
          description: "Campaign identifier"
      dataType: string
      required: false
  fields:  # Required for 'lead' and 'accountPerson'
    - serviceAttribute: email
      dataType: string
      required: true
      description: Person email address
  accountFields:  # Required for 'account' and 'accountPerson'
    - serviceAttribute: accountName
      dataType: string
      required: true
      description: Account name
  headers:
    - name: X-Custom-Header
      value: 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

Property

Type

Required

Description

serviceAttribute

string

Yes

Field name used by your service

dataType

string

Yes

Data type (see Data Types below)

required

boolean

Whether field is required (defaults to false)

description

string

Human-readable description for admins (recommended but optional)

Attribute definition properties

For globalAttributes, flowAttributes, and callbackPayloadDef.attributes, each attribute must include:

Property

Type

Required

Description

apiName

string

Yes

API name for the attribute

i18n

object

Yes

Internationalized display information

i18n.en_US

object

Yes

English (US) localization — always required

i18n.en_US.displayName

string

Yes

Display name shown to users in the UI

i18n.en_US.description

string

Optional description (recommended for clarity)

i18n.<locale>

object

Additional locale (e.g. fr_FR, de_DE, ja_JP) — same shape as en_US

i18n.<locale>.displayName

string

Yes (per locale)

Localized display name

i18n.<locale>.description

string

Localized description

dataType

string

Yes

Data type: string, integer, float, boolean, date, datetime

required

boolean

Whether this attribute is required (defaults to false)

Example with multiple locales:

- apiName: enrichmentType
  i18n:
    en_US:
      displayName: "Enrichment Type"
      description: "Type of enrichment to perform"
    fr_FR:
      displayName: "Type d'enrichissement"
      description: "Type d'enrichissement à effectuer"
    de_DE:
      displayName: "Anreicherungstyp"
      description: "Art der durchzuführenden Anreicherung"
  dataType: string
  required: true

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: string
      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:
    - apiName: processingStatus
      i18n:
        en_US:
          displayName: "Processing Status"
          description: "Processing status"
      dataType: string
      required: false

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 (0-100)
  - accessorName: treatmentId
    dataType: string
    description: Recommended treatment (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: "enrichmentType"
supportedEntityType: lead
enableSplitPaths: true
timeout: 120

invocationPayloadDef:
  globalAttributes:
    - apiName: apiKey
      i18n:
        en_US:
          displayName: "API Key"
          description: "Service API key"
      dataType: string
      required: true
    - apiName: region
      i18n:
        en_US:
          displayName: "Data Region"
          description: "Data region (US, EU, APAC)"
      dataType: string
      required: false
  flowAttributes:
    - apiName: enrichmentType
      i18n:
        en_US:
          displayName: "Enrichment Type"
          description: "Type of enrichment to perform"
      dataType: string
      required: true
  fields:
    - serviceAttribute: email
      dataType: string
      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:
    - name: X-Tenant-ID
      value: subscription.imsOrgId
      description: Tenant identifier
  journeyContext: true
  subscriptionContext: true
  accessorsMetadata:
    - accessorName: enrichmentScore
      dataType: integer
      description: Data quality score (0-100)
    - accessorName: dataQuality
      dataType: string
      description: Data quality level (high, medium, low)

callbackPayloadDef:
  fields:
    - serviceAttribute: email
      dataType: string
      description: Verified email address
    - serviceAttribute: mobilePhone
      dataType: string
      description: Enriched mobile phone
    - serviceAttribute: linkedInUrl
      dataType: string
      description: LinkedIn profile URL
    - serviceAttribute: seniority
      dataType: string
      description: Job seniority level
  attributes:
    - apiName: enrichmentStatus
      i18n:
        en_US:
          displayName: "Enrichment Status"
          description: "Enrichment processing status"
      dataType: string
      required: false
    - apiName: enrichmentDate
      i18n:
        en_US:
          displayName: "Enrichment Date"
          description: "When enrichment was performed"
      dataType: datetime
      required: false

Validation

Adobe validates your service definition with:

Schema validation: Ensures that all required fields are present.
Entity type validation: Checks conditional field requirements in invocationPayloadDef.
- lead requires fields
- account requires accountFields
- accountPerson requires at least one of fields or accountFields
- callbackPayloadDef fields and accountFields are always optional — your service may legitimately have nothing to write back (e.g., a scoring-only service that only populates attributes or accessorsMetadata)
Split path validation: When enableSplitPaths: true, requires accessorsMetadata.
Data type validation: Ensures that data types are valid.

Best Practices

Use descriptive names: Make serviceAttribute and apiName values clear and intuitive.
Provide good descriptions: Help admins understand field purposes.
Mark fields required carefully: Only require truly necessary fields.
Use valid data types: Allowed values are string, integer, float, boolean, date, datetime.
Define clear accessors: When using split paths, provide meaningful accessor names and descriptions.
Include i18n: Always provide displayName in i18n.en_US for globalAttributes, flowAttributes, and callbackPayloadDef.attributes.