Skip to content
Console(opens in a new tab)

GraphQL quickstart

Learn how a GraphQL query reads Enigma data, send your first search, and read the result.

The Enigma GraphQL API gives you the business graph: brands, operating locations, legal entities, people, and addresses, and the records that connect them. You describe a business, Enigma matches it, and you choose the fields that come back. This page takes you from an API key to your first result.

Every query has the same parts.

Part What it means
Intent The kind of answer. search returns records.
Subject The kind of record: entityType: BRAND in the input, and ... on Brand where you read.
Match Your description of the business, such as its name, website, or address.
Connection A path to related records, read through edges { node { … } }.
Selection The fields that come back. You pay only for the data products you select.

The anatomy of a query explains each part with one full example.

You need:

  • An Enigma account on a plan with API access: Pro, Max, or Enterprise. See Credits and pricing.
  • An API key. In Enigma Console, go to Settings, then Account, then API keys.
  • A terminal with curl.
  1. Store your API key.

    Terminal window
    export ENIGMA_API_KEY='replace_with_your_api_key'
  2. Send a search.

    This search finds the brand Enigma Technologies, and reads one name and one website.

    Request
    curl https://api.enigma.com/graphql \
    --request POST \
    --header "x-api-key: $ENIGMA_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
    "query": "query FindBrand($name: String) { search(searchInput: { entityType: BRAND, name: $name, conditions: { limit: 1 } }) { ... on Brand { id names(first: 1) { edges { node { name } } } websites(first: 1) { edges { node { website } } } } } }",
    "variables": { "name": "Enigma Technologies" }
    }'
    • conditions: { limit: 1 } asks for the single best match.
    • first: 1 reads one record from each connection.
    • Set Content-Type to application/json exactly. The API rejects a header with a parameter, such as ; charset=utf-8.
  3. Read the response.

    Response
    {
    "data": {
    "search": [
    {
    "id": "5f53e079-c66a-487e-8a9d-08efc39652ee",
    "names": { "edges": [{ "node": { "name": "ENIGMA TECHNOLOGIES" } }] },
    "websites": { "edges": [{ "node": { "website": "https://enigma.io" } }] }
    }
    ]
    }
    }
    • data.search is a list of matched records, best match first.
    • Each connection returns its records in edges, one node for each record.
    • This search uses 4 credits: Brand Name and Website, at 2 credits each. id is free.
Part What it tells you
HTTP status Whether the API accepted and ran the request. See status codes.
data.search The matched records. An empty list means that no record matched.
errors A list of error messages, as plain strings. A response can hold data and errors together.

These examples go from the smallest query to one that reads several data products. Send each one as the query value of the request in step 2. Each response is from a real search, and each cost uses the list prices on the rate card.

The smallest useful query. It returns only the ID of the best match.

query {
search(searchInput: { entityType: BRAND, name: "Enigma Technologies", conditions: { limit: 1 } }) {
... on Brand { id }
}
}
Response
{ "data": { "search": [{ "id": "5f53e079-c66a-487e-8a9d-08efc39652ee" }] } }

Cost: 0 credits. id is free.

A match can use other identifiers than a name. This search finds the same brand by its website.

query {
search(searchInput: { entityType: BRAND, website: "enigma.com", conditions: { limit: 1 } }) {
... on Brand {
id
names(first: 1) { edges { node { name } } }
}
}
}
Response
{
"data": {
"search": [
{
"id": "5f53e079-c66a-487e-8a9d-08efc39652ee",
"names": { "edges": [{ "node": { "name": "ENIGMA TECHNOLOGIES" } }] }
}
]
}
}

Cost: Brand Name 1 × 2 = 2 credits.

Set entityType to OPERATING_LOCATION to find a single place of business. An address tells apart the locations of a brand.

query {
search(searchInput: {
entityType: OPERATING_LOCATION
name: "Safeway"
address: { street1: "5918 Stoneridge Mall Rd", city: "Pleasanton", state: "CA" }
conditions: { limit: 1 }
}) {
... on OperatingLocation {
id
names(first: 1) { edges { node { name } } }
addresses(first: 1) { edges { node { fullAddress } } }
}
}
}
Response
{
"data": {
"search": [
{
"id": "c458c91f-907c-4ec1-bbe1-e9b39baee074",
"names": { "edges": [{ "node": { "name": "SAFEWAY" } }] },
"addresses": { "edges": [{ "node": { "fullAddress": "5918 STONERIDGE MALL RD PLEASANTON CA 94588" } }] }
}
]
}
}

Cost: Operating Location Name 1 × 2 + Address 1 × 2 = 4 credits.

conditions on a connection narrows and orders the related records. This search reads the five Safeway locations in Texas with the highest card revenue.

query {
search(searchInput: { entityType: BRAND, name: "Safeway", conditions: { limit: 1 } }) {
... on Brand {
id
operatingLocations(first: 5, conditions: {
filter: { EQ: ["addresses.state", "TX"] }
orderBy: ["cardTransactions.projectedQuantity DESC"]
}) {
edges { node { addresses(first: 1) { edges { node { streetAddress1 city } } } } }
}
}
}
}
Response (first 2 of 5 locations)
{
"data": {
"search": [
{
"id": "0f26fbef-3436-4f85-8bcd-31fe12a4f99a",
"operatingLocations": {
"edges": [
{ "node": { "addresses": { "edges": [{ "node": { "streetAddress1": "200 FREEDOM DR", "city": "ROANOKE" } }] } } },
{ "node": { "addresses": { "edges": [{ "node": { "streetAddress1": "743 HENRIETTA CREEK RD", "city": "ROANOKE" } }] } } }
]
}
}
]
}
}

Cost: Address 5 × 2 = 10 credits. The filter and the sort are free.

One query can read several data products, a math field, and a related record. Aliases such as locationCount name the fields in the response.

query {
search(searchInput: { entityType: BRAND, name: "Safeway", conditions: { limit: 1 } }) {
... on Brand {
id
names(first: 1) { edges { node { name } } }
locationCount: count(field: "operatingLocations")
revenue12m: cardTransactions(first: 1, conditions: { filter: { AND: [
{ EQ: ["period", "12m"] },
{ EQ: ["quantityType", "card_revenue_amount"] }
] } }) {
edges { node { projectedQuantity periodEndDate } }
}
legalEntities(first: 1) {
edges { node { names(first: 1) { edges { node { name } } } } }
}
}
}
}
Response
{
"data": {
"search": [
{
"id": "0f26fbef-3436-4f85-8bcd-31fe12a4f99a",
"names": { "edges": [{ "node": { "name": "SAFEWAY" } }] },
"locationCount": 1307,
"revenue12m": { "edges": [{ "node": { "projectedQuantity": 25534953930, "periodEndDate": "2026-07-31" } }] },
"legalEntities": { "edges": [{ "node": { "names": { "edges": [{ "node": { "name": "SAFEWAY, INC." } }] } } }] }
}
]
}
}

Cost: Brand Name 2 + Brand 12M Card Revenue Amount 10 + Legal Entity Name 5 = 17 credits. count is free.

Connections nest to any depth that you need, up to the depth limit of 40. This search follows the brand to its legal entity, the legal entity’s state registrations and tax ID, and two of the brand’s locations. Each line names the data product it uses.

query {
search(searchInput: { entityType: BRAND, name: "Safeway", conditions: { limit: 1 } }) {
... on Brand {
id
names(first: 1) { edges { node { name } } } # Brand Name
legalEntities(first: 1) {
edges { node {
names(first: 1) { edges { node { name } } } # Legal Entity Name
tins(first: 1) { edges { node { tin tinType } } } # EIN
registeredEntities(first: 1) {
edges { node {
name # Registered Entity Name
registrations(first: 2) {
edges { node {
registrationState fileNumber issueDate # Registration details
status # Registration Status
} }
}
} }
}
} }
}
operatingLocations(first: 2) {
edges { node {
names(first: 1) { edges { node { name } } } # Operating Location Name
addresses(first: 1) { edges { node { fullAddress } } } # Address
phoneNumbers(first: 1) { edges { node { phoneNumber } } } # Phone Number
operatingStatuses(first: 1) { edges { node { operatingStatus } } } # Operating Status
} }
}
}
}
}
Response
{
"data": {
"search": [
{
"id": "0f26fbef-3436-4f85-8bcd-31fe12a4f99a",
"names": { "edges": [{ "node": { "name": "SAFEWAY" } }] },
"legalEntities": {
"edges": [
{
"node": {
"names": { "edges": [{ "node": { "name": "SAFEWAY, INC." } }] },
"tins": { "edges": [{ "node": { "tin": "264563006", "tinType": "EIN" } }] },
"registeredEntities": {
"edges": [
{
"node": {
"name": "SAFEWAY, INC.",
"registrations": {
"edges": [
{
"node": {
"registrationState": "DE",
"fileNumber": "2096948",
"issueDate": "1986-07-23",
"status": "unknown"
}
},
{
"node": {
"registrationState": "CA",
"fileNumber": "1543561",
"issueDate": "1986-10-06",
"status": "active"
}
}
]
}
}
}
]
}
}
}
]
},
"operatingLocations": {
"edges": [
{
"node": {
"names": { "edges": [{ "node": { "name": "SAFEWAYTAX" } }] },
"addresses": {
"edges": [
{
"node": { "fullAddress": "18952 MACARTHUR BLVD STE 230 IRVINE CA 92612" }
}
]
},
"phoneNumbers": { "edges": [{ "node": { "phoneNumber": "+18002182260" } }] },
"operatingStatuses": { "edges": [{ "node": { "operatingStatus": "Open" } }] }
}
},
{
"node": {
"names": { "edges": [{ "node": { "name": "SAFEWAY" } }] },
"addresses": { "edges": [{ "node": { "fullAddress": "97 N MILL RD VINELAND NJ 08360" } }] },
"phoneNumbers": { "edges": [{ "node": { "phoneNumber": "+18566919696" } }] },
"operatingStatuses": { "edges": [{ "node": { "operatingStatus": "Open" } }] }
}
}
]
}
}
]
}
}
Data product Records Credits
Brand Name 1 2
Legal Entity Name 1 5
EIN 1 3
Registered Entity Name 1 1
Registration details 2 20
Registration Status 2 10
Operating Location Name 2 4
Address 2 4
Phone Number 2 2
Operating Status 2 4
Total 55

status is in the same registration as the other fields, but it is a separate data product. Each record of a connection counts again, so first: 2 on operatingLocations doubles the cost of every location field.

Intent Use it when
search You want records and their fields.
aggregate You want a count of operating locations, not the records. It uses no credits.
createList and createListMaterialization You want a file of many records.

Choose an intent covers every intent.

  • Select only the fields you need. Each data product you select is charged for each record. See Credits and pricing.
  • Set first on every connection. Without it, a connection returns 3, 10, or 100 records, and you pay for each one. See connections.
  • Send one operation in each request. The API ignores operationName.
  • Keep queries shallow. A query deeper than 40 levels fails with a 400 response.
  • Handle errors as strings. They are not GraphQL error objects. See response.