Synchronise your customer data

Cycle allow you to synchronise your customer data at company level.

Initial import

If you're just getting started, you’ll want to import your existing company and user data into Cycle. Here’s how to format your CSV for import:

companyName,name,email,customId,attioId,zendeskId,hubspotId,intercomId,pipedriveId,snowflakeId,salesforceId
Acme,John Doe,[e-mail],acme-001,a123,zendesk_456,hubspot_789,int_001,pipe_999,sf_acme_1,sf_001
Acme,Jane Doe,[e-mail],acme-001,a123,zendesk_456,hubspot_789,int_001,pipe_999,sf_acme_1,sf_001
Wayne Enterprises,Bruce Wayne,[e-mail],wayne-001,a555,zendesk_789,hubspot_321,int_003,pipe_777,sf_wayne_1,sf_003
Airbnb,Main contact,[e-mail],airbnb-001,a777,zendesk_000,hubspot_000,int_004,pipe_666,sf_airbnb_1,sf_004

Field name	Description
companyName	The name of the company
name	The full name of the person (Or `Main contact`)
email	Their email (or `[e-mail]`)
customId (optional)	ID of your choice
attioId (optional)	ID of your Attio CRM
zendeskId (optional)	ID of your Zendesk CRM
hubspotId (optional)	ID of your HubSpot CRM
intercomId (optional)	ID of your Intercom CRM
pipedrive (optional)	ID of your Pipedrive CRM
snowflakeId (optional)	ID of your Snowflake CRM

Note that every row correspond to people granularity, so if you do not have any human contact but only a company, as the last row in the above example, use a Main contact approach.

IDs allow you later to match company via ID. So they are attached to Company and not people

---

Once your CSV is ready, you can upload it using Cycle’s GraphQL API.

Here’s the mutation to use:

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

Examples

cURL

curl https://api.product.cycle.app/graphql \
  -X POST \
  -H "Authorization: Bearer YOUR_CYCLE_API_KEY" \
  -F operations='{
    "query": "mutation importCustomersFromCSV($file: Upload!, $workspaceId: ID!) { importCustomersFromCSV(csvFile: $file, productId: $workspaceId) }",
    "variables": { "file": null, "workspaceId": "YOUR_WORKSPACE_ID" }
  }' \
  -F map='{ "0": ["variables.file"] }' \
  -F 0=@your_file.csv

NodeJS

import fs from 'fs';
import path from 'path';
import FormData from 'form-data';

const apiKey = 'YOUR_CYCLE_API_KEY';
const workspaceId = 'YOUR_WORKSPACE_ID';
const csvPath = './your_file.csv';

const form = new FormData();

form.append(
  'operations',
  JSON.stringify({
    query: `
      mutation importCustomersFromCSV($file: Upload!, $workspaceId: ID!) {
        importCustomersFromCSV(csvFile: $file, productId: $workspaceId)
      }
    `,
    variables: {
      file: null,
      workspaceId,
    },
  })
);

form.append('map', JSON.stringify({ '0': ['variables.file'] }));
form.append('0', fs.createReadStream(csvPath));

const response = await fetch('https://api.product.cycle.app/graphql', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    ...form.getHeaders(),
  },
  body: form,
});

const result = await response.json();
console.log(result);

Python

import requests

# Replace with your actual values
API_KEY = 'YOUR_CYCLE_API_KEY'
WORKSPACE_ID = 'YOUR_WORKSPACE_ID'
CSV_PATH = 'your_file.csv'

url = 'https://api.product.cycle.app/graphql'

headers = {
    'Authorization': f'Bearer {API_KEY}'
}

operations = {
    "query": """
        mutation importCustomersFromCSV($file: Upload!, $workspaceId: ID!) {
            importCustomersFromCSV(csvFile: $file, productId: $workspaceId)
        }
    """,
    "variables": {
        "file": None,
        "workspaceId": WORKSPACE_ID
    }
}

map_ = {
    "0": ["variables.file"]
}

files = {
    'operations': (None, json.dumps(operations), 'application/json'),
    'map': (None, json.dumps(map_), 'application/json'),
    '0': (CSV_PATH, open(CSV_PATH, 'rb'), 'text/csv'),
}

response = requests.post(url, headers=headers, files=files)
print(response.status_code)
print(response.json())

Real-time sync with your CRM

Once your companies are in Cycle, you’ll want to keep them in sync with your CRM. There are two situations to handle:

1. When something changes in your CRM e.g. a company stage changes to “Closed Won”

2. When a new company is created in Cycle e.g. from feedback or form submissions

Example: Syncing updates from CRM to Cycle

Let’s say you just updated Acme’s stage to Closed Won in your CRM. You now want to reflect that change in Cycle.

To do that, you need to 👇

Step 1: Fetch the attribute definition ID

Before updating any company attribute, you need to retrieve the definition ID of the attribute (e.g. Stage) 👉 In this case we assume Stage is a Select value, so you will also need the value id

GraphQL query:

query workspaceBySlug($slug: DefaultString!) {
    getProductBySlug(slug: $slug) {
        id
        name
        slug
        companyAttributeDefinitions(
            pagination: {
                size: 100,
                where: {
                    cursor: "",
                    direction: AFTER
                }
            }
        ) {
            pageInfo {
                endCursor
                hasNextPage
            }
            edges {
                node {
                    __typename
                    ... on AttributeTextDefinition {
                        id
                        name
                    }
                    ... on AttributeNumberDefinition {
                        id
                        name
                    }
                    ... on AttributeCheckboxDefinition {
                        id
                        name
                    }
                    ... on AttributeSingleSelectDefinition {
                        id
                        name
                        valuesV2(pagination: {
                            size: 100,
                            where: {
                                cursor: "",
                                direction: AFTER
                            }
                        }) {
                            edges {
                                node {
                                    id
                                    value
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

This will return a list of all attribute definitions available in your workspace.

Find the one named Stage and copy its id (and the corresponding valueId if it's a select field).

Step 2: Update the company in Cycle

Once you have the attributeDefinitionId and (if needed) the valueId, use the following mutation:

updateCompanyAttributeValue(
  $companyId: ID!
  $attributeDefinitionId: ID!
  $value: CompanyAttributeValueInput!
) {
  updateCompanyAttributeValue(
    companyId: $companyId
    attributeDefinitionId: $attributeDefinitionId
    value: $value
  ) {
    __typename
    ... on CompanyAttributeCheckbox {
      id
      definition {
        id
        __typename
      }
      value {
        id
        valueCheckbox: value
      }
    }
    ... on CompanyAttributeText {
      id
      definition {
        id
        __typename
      }
      value {
        id
        valueText: value
      }
    }
    ... on CompanyAttributeSingleSelect {
      id
      definition {
        id
        __typename
      }
      value {
        id
        valueSelect: value
      }
    }
  }
}

Examples

cURL

curl https://api.product.cycle.app/graphql \
  -X POST \
  -H "Authorization: Bearer YOUR_CYCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation updateCompanyAttributeValue($companyId: ID!, $attributeDefinitionId: ID!, $value: CompanyAttributeValueInput!) { updateCompanyAttributeValue(companyId: $companyId, attributeDefinitionId: $attributeDefinitionId, value: $value) { __typename ... on CompanyAttributeSingleSelect { id definition { id __typename } value { id valueSelect: value } } } }",
    "variables": {
      "companyId": "company-id-of-acme",
      "attributeDefinitionId": "definition-id-of-stage",
      "value": {
        "select": "value-id-for-closed-won"
      }
    }
  }'

NodeJS

const response = await fetch('https://api.product.cycle.app/graphql', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_CYCLE_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: `
      mutation updateCompanyAttributeValue(
        $companyId: ID!, 
        $attributeDefinitionId: ID!, 
        $value: CompanyAttributeValueInput!
      ) {
        updateCompanyAttributeValue(
          companyId: $companyId,
          attributeDefinitionId: $attributeDefinitionId,
          value: $value
        ) {
          __typename
          ... on CompanyAttributeSingleSelect {
            id
            definition { id __typename }
            value { id valueSelect: value }
          }
        }
      }
    `,
    variables: {
      companyId: 'company-id-of-acme',
      attributeDefinitionId: 'definition-id-of-stage',
      value: { select: 'value-id-for-closed-won' },
    },
  }),
});

const result = await response.json();
console.log(result);

Python

import requests
import json

url = 'https://api.product.cycle.app/graphql'
headers = {
    'Authorization': 'Bearer YOUR_CYCLE_API_KEY',
    'Content-Type': 'application/json'
}

query = """
mutation updateCompanyAttributeValue(
  $companyId: ID!, 
  $attributeDefinitionId: ID!, 
  $value: CompanyAttributeValueInput!
) {
  updateCompanyAttributeValue(
    companyId: $companyId,
    attributeDefinitionId: $attributeDefinitionId,
    value: $value
  ) {
    __typename
    ... on CompanyAttributeSingleSelect {
      id
      definition { id __typename }
      value { id valueSelect: value }
    }
  }
}
"""

variables = {
    "companyId": "company-id-of-acme",
    "attributeDefinitionId": "definition-id-of-stage",
    "value": {
        "select": "value-id-for-closed-won"
    }
}

response = requests.post(url, headers=headers, json={
    "query": query,
    "variables": variables
})

print(response.status_code)
print(response.json())

Example: Syncing updates when new company is created in Cycle

Work in progress ⏳

Daily synchronisation

A very typical way of keeping your data in-sync would be to have a cron job who run every day and update in bulk all your companies that changed during the last day.

• Fetch companies from your database that were updated in the last 24 hours

• Generate a CSV with those companies and the latest values

• Use the mutation below to update them in bulk in Cycle

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

⚠️ You must define which column to use as the unique company identifier during the update. It can be one of these: companyName, customId, attioId, zendeskId, hubspotId, intercomId, pipedriveId, snowflakeId, salesforceId

Cycle will use this column to match each row with an existing company in your workspace.

CSV format

Here’s an example of how your update CSV could look:

companyName	customId	attioId	zendeskId	hubspotId	intercomId	pipedriveId	snowflakeId	salesforceId	arr	numberOfEmployees	country	leadStatus	industry	closedDate	custom attribute
Acme			...			...			...			...			...			...			...			250000	50	France	Closed	HR	1678670383	...

Each column corresponds to an attribute in Cycle. You can update as many fields as you want in one go — just make sure the header names match exactly with the attribute names defined in your workspace (case-sensitive!).

Once your CSV is ready, upload it via the updateCompanyAttributeValuesFromCSV mutation.