Skip to content

Create enrichment

POST/enrichment-pivots

Live Discover API · Live Discover

Create a new enrichment.

Required permissionlive-discover.query-catalog:write

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.

Request body

Content type: application/json

Request body fields

namestringrequired
Enrichment name.
Must match the pattern ^[\p{L}\p{N}][-\p{L}\p{N}. ]*[\p{L}\p{N}]$. Must be 1–255 characters long.
descriptionstringrequired
Enrichment description.
Must match the pattern ^[-\p{L}\p{N}\d ,.]+$. Must be 1–1024 characters long.
urlstringrequired
Enrichment URL. This must start with http:// or https:// and contain at least one of the supported variables (ipAddress, dns, port, sha256, md5) delimited by $$. Variables may be used only after the first / following the domain name.
Must match the pattern ^https?://[^/$]+[/][^$]*(?:[$]{2}(?:ipAddress|dns|port|sha256|md5)[$]{2}[^$]*)+$. Must be 17–1024 characters long.
typestring (enum)required
Enrichment type.
Must be one of: ipAddress, md5, sha256, dns, port, geolocation.

Request samples

curl -X POST "https://api-<data-region>.central.sophos.com/live-discover/v1/enrichment-pivots" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"name\": \"VirusTotal\",
  \"description\": \"Lookup the IP Address on Virus Total\",
  \"url\": \"https://enrichment.example.com/lookup?ip=\$\$ipAddress\$\$\",
  \"type\": \"ipAddress\"
}"


import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/live-discover/v1/enrichment-pivots",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   'name': 'VirusTotal',
    'description': 'Lookup the IP Address on Virus Total',
    'url': 'https://enrichment.example.com/lookup?ip=$$ipAddress$$',
    'type': 'ipAddress'},
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "name": "VirusTotal",
  "description": "Lookup the IP Address on Virus Total",
  "url": "https://enrichment.example.com/lookup?ip=$$ipAddress$$",
  "type": "ipAddress"
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/live-discover/v1/enrichment-pivots" -Headers $headers -Body $body -ContentType "application/json"


package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    req, err := http.NewRequest("POST", "https://api-<data-region>.central.sophos.com/live-discover/v1/enrichment-pivots", strings.NewReader(`{
  "name": "VirusTotal",
  "description": "Lookup the IP Address on Virus Total",
  "url": "https://enrichment.example.com/lookup?ip=$$ipAddress$$",
  "type": "ipAddress"
}`))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}


const response = await fetch("https://api-<data-region>.central.sophos.com/live-discover/v1/enrichment-pivots", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "VirusTotal",
  "description": "Lookup the IP Address on Virus Total",
  "url": "https://enrichment.example.com/lookup?ip=$$ipAddress$$",
  "type": "ipAddress"
}),
});
const data = await response.json();
console.log(data);

Responses

201 — New enrichment.

Response fields

idstring (uuid)
Enrichment ID.
tenantobject
Tenant these resources belong to.
Show child attributesHide child attributes
idstring (uuid)required
namestring
sourceTypestring (enum)required
Enrichment source type.
Must be one of: canned, custom.
namestringrequired
Enrichment name.
descriptionstringrequired
Enrichment description.
typestring (enum)required
Enrichment type.
Must be one of: ipAddress, md5, sha256, dns, port, geolocation.
urlstringrequired
Enrichment URL.
createdAtstring (datetime)
When the enrichment was created.
createdByobject
Principal reference.
Show child attributesHide child attributes
idstring (uuid)required
Principal ID. This is the client ID for service principals.
typestring (enum)required
Principal type.
Must be one of: user, service.
namestring
Principal name. This doesn't apply to service principals.
accountTypestring
Account type.
Must be one of: partner, tenant, organization.
updatedAtstring (datetime)
When the enrichment was last updated.
updatedByobject
Principal reference.
Show child attributesHide child attributes
idstring (uuid)required
Principal ID. This is the client ID for service principals.
typestring (enum)required
Principal type.
Must be one of: user, service.
namestring
Principal name. This doesn't apply to service principals.
accountTypestring
Account type.
Must be one of: partner, tenant, organization.

Errors

Status Meaning
400 Bad request.
403 Forbidden.
500 Unexpected error.

All error responses share the same shape — see the error response object.

Response examples

201

{
  "id": "00000000-0000-0000-0000-000000000000",
  "tenant": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string"
  },
  "sourceType": "canned",
  "name": "string",
  "description": "string",
  "type": "ipAddress",
  "url": "string",
  "createdAt": "string",
  "createdBy": {
    "id": "00000000-0000-0000-0000-000000000000",
    "type": "user",
    "name": "string",
    "accountType": "partner"
  },
  "updatedAt": "string",
  "updatedBy": {
    "id": "00000000-0000-0000-0000-000000000000",
    "type": "user",
    "name": "string",
    "accountType": "partner"
  }
}

See the guide for a narrative walkthrough of this API.