- Docs
- Guides
- Build with Enigma
- GraphQL API
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.
How a query works
Section titled “How a query works”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.
Before you begin
Section titled “Before you begin”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.
Make your first request
Section titled “Make your first request”-
Store your API key.
Terminal window export ENIGMA_API_KEY='replace_with_your_api_key' -
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: 1reads one record from each connection.- Set
Content-Typetoapplication/jsonexactly. The API rejects a header with a parameter, such as; charset=utf-8.
-
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.searchis a list of matched records, best match first.- Each connection returns its records in
edges, onenodefor each record. - This search uses 4 credits: Brand Name and Website, at 2 credits each.
idis free.
Interpret the result
Section titled “Interpret the result”| 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. |
More examples
Section titled “More examples”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.
Find a record by name
Section titled “Find a record by name”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 } }}{ "data": { "search": [{ "id": "5f53e079-c66a-487e-8a9d-08efc39652ee" }] } }Cost: 0 credits. id is free.
Match by website
Section titled “Match by website”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 } } } } }}{ "data": { "search": [ { "id": "5f53e079-c66a-487e-8a9d-08efc39652ee", "names": { "edges": [{ "node": { "name": "ENIGMA TECHNOLOGIES" } }] } } ] }}Cost: Brand Name 1 × 2 = 2 credits.
Find one location by name and address
Section titled “Find one location by name and address”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 } } } } }}{ "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.
Filter and sort a connection
Section titled “Filter and sort a connection”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 } } } } } } } }}{ "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.
Build a brand profile
Section titled “Build a brand profile”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 } } } } } } } }}{ "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.
Read nested records
Section titled “Read nested records”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 } } } } }}{ "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.
Choose the right intent
Section titled “Choose the right intent”| 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.
Before you go live
Section titled “Before you go live”- Select only the fields you need. Each data product you select is charged for each record. See Credits and pricing.
- Set
firston 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
errorsas strings. They are not GraphQL error objects. See response.