Customer Data Ingestion

Cycle’s GraphQL API helps you maintain a single, reliable source of truth for your customer data. This guide walks you through the essential mutations needed to import and manage customer and company information in Cycle.

From defining custom attributes to importing historical data in bulk, this page outlines the full ingestion flow using GraphQL—ensuring your data stays clean, up-to-date, and structured for scale.

---

Setup – define the attributes you’ll sync

Custom attributes are available for companies only. People inherit whatever their company holds.

Attribute types

GraphQL kind	Use‑case	Example	Creation field
TEXT	Free text	acme.com	scalar
NUMBER	Numeric metric	12500	scalar
CHECKBOX	Boolean	true	scalar
DATE	Date / timestamp	2025‑05‑09	scalar
SINGLE_SELECT	Controlled list	Closed Won	select

General mutation

mutation AddCompanyAttribute(
  $workspaceId: ID!
  $name: String!
  $color: String = "a"
  $type: CompanyAttributeInputType!
) {
  addNewCompanyAttribute(
    input: {
      productId: $workspaceId
      name: $name
      color: $color
      type: $type
    }
  ) { id }
}

Where CompanyAttributeInputType is either:

• { scalar: { type: AttributeScalarType! } }

• { select: { type: SINGLE_SELECT, values: [String!]! } }

Example – TEXT

mutation {
  addNewCompanyAttribute(
    input: {
      productId: "ws_123"
      name: "Website"
      color: "a"
      type: { scalar: { type: TEXT } }
    }
  ) { id }
}

Example – SINGLE_SELECT

mutation {
  addNewCompanyAttribute(
    input: {
      productId: "ws_123"
      name: "Lifecycle Stage"
      color: "b"
      type: {
        select: {
          type: SINGLE_SELECT
          values: ["Prospect", "Closed Won", "Churned"]
        }
      }
    }
  ) { id }
}

---

Customer (People) Importer

Use importCustomersFromCSV to load people (and their companies) in bulk—perfect for your initial historical load.

Minimal CSV schema

Column	Required?	Purpose
companyName	Yes	Company display name (fallback identifier)
name	Yes	Person’s full name or Main contact placeholder
email	Yes	Primary identifier for the person
Unique IDs (customId, hubspotId, salesforceId, …)	Optional	Stable IDs so re‑imports update not duplicate

Cycle silently ignores columns it doesn’t recognise.

mutation importCustomersFromCSV($file: Upload!, $workspaceId: ID!) {
  importCustomersFromCSV(csvFile: $file, productId: $workspaceId)
}

Bulk CSV import is processed asynchronously and is not subject to the 2 000‑mutation/hour rate limit.

---

Company Importer – daily delta & upsert

Use updateCompanyAttributeValuesFromCSV to for both big (historical) imports and daily sync like updates.

Minimal CSV schema

Import name	Label	Required?	Type	Purpose
Any unique identifier:customId, hubspotId, salesforceId, attioId, zendeskId, intercomId, pipedriveId, snowflakeId, companyName	Respectively: customId, hubspotId, salesforceId, attioId, zendeskId, intercomId, pipedriveId, snowflakeId, Company Name	Yes	Text	Used to match the company
arr	ARR	Optional	Integer	Annual Recurring Revenue
leadStatus	Lead Status	Optional	Text	Latest lead status for the company
closeDate	Close Date	Optional	Date (millisecond unix)	Date the deal was closed
industry	Industry	Optional	Text	Industry of the company
numberOfEmployees	Employees	Optional	Integer	Amount of employees at the company
Any of your custom attributes	Same as import name	Optional	Integer, Text, Date or Single select	New value you want to set

Upsert vs. update

Parameter	Behaviour
createCompanies: false (default)	Rows whose identifier doesn’t match an existing company are skipped.
createCompanies: true	Cycle creates the company first, then applies the updates. Ideal for nightly upserts.

Mutation

mutation UpdateCompanies($file: Upload!, $workspaceId: ID!, $create: Boolean!) {
  updateCompanyAttributeValuesFromCSV(
    csvFile: $file
    productId: $workspaceId
    createCompanies: $create
  )
}

That’s it—you now have everything needed to setup and ingest clean customer data into Cycle. 🎉