API Docs

Managing References

Flowcase lets you store customers and related reference projects centrally, making it easy to include them in proposals and standardise how they appear in consultants' CVs. If you manage reference projects in an external system such as Maconomy or Deltek Vantagepoint, you can use the Flowcase API to keep them in sync.

This guide walks through the typical workflow for synchronising customers and reference projects into Flowcase.

Before you start

You will need:

  • An API key with the referencemanager or internationalmanager role. Project owners can edit their own projects without either role, but publishing needs the publish permission. See Authentication & Security and Reference Projects.
  • Familiarity with how multilingual text fields work in the Flowcase API. Names, descriptions, and other text fields accept an object keyed by language code (e.g. "en" for English, "no" for Norwegian). See Country & Language Codes for the full list.

Concepts

Customers represent the client organisations your company has delivered work for. Each customer can have multiple reference projects linked to it. A reference project documents a delivered engagement. Its scope, timeframe, challenges, solutions, and outcomes.

Every reference project must belong to a customer, so you always need to create or look up the customer first.

Step 1: Sync customers

Check if a customer already exists

Before creating a customer, check whether it already exists. If your external system assigns a stable ID to each customer, you can look it up by external ID:

GET https://<subdomain>.flowcase.com/api/v2/company/cv/customers/find?external_unique_id=<external_id>

Alternatively, search by name:

GET https://<subdomain>.flowcase.com/api/v2/company/cv/customers?customer_name=<name>&size=10&offset=0

Create a new customer

POST https://<subdomain>.flowcase.com/api/v2/company/cv/customers

{
  "company_customer": {
    "external_unique_id": "EXT-1234",
    "customer_name": {
      "en": "Acme Corporation",
      "no": "Acme Corporation"
    },
    "customer_description": {
      "en": "Global technology company"
    },
    "customer_url": "https://example.com",
    "industry_id": "<industry_id>"
  }
}

Store the external_unique_id so that subsequent sync runs can match existing customers rather than creating duplicates.

Update an existing customer

PUT https://<subdomain>.flowcase.com/api/v2/company/cv/customers/<customer_id>

Only include the fields you want to change. The request body uses the same company_customer wrapper as creation.

Step 2: Sync reference projects

Check if a project already exists

If your external system assigns a stable ID, you can look up a project by external ID, just like customers:

GET https://<subdomain>.flowcase.com/api/v2/company/cv/projects/find?external_unique_id=<external_id>

You do not need to know the parent customer ID: the search is scoped to all projects in the account.

Alternatively, use the search endpoint to find projects by text. Search reference projects lists every filter it accepts:

POST https://<subdomain>.flowcase.com/api/v4/references/search

{
  "offset": 0,
  "size": 10,
  "must": [
    {
      "query": {
        "value": "<search_term>"
      }
    }
  ]
}

Create a new reference project

A project is always created under a customer:

POST https://<subdomain>.flowcase.com/api/v2/company/cv/customers/<customer_id>/projects

{
  "company_project": {
    "external_unique_id": "SAP-5678",
    "project_name": {
      "en": "Cloud Migration Programme"
    },
    "project_description": {
      "en": "Migrated on-premise infrastructure to Azure"
    },
    "month_from": "1",
    "year_from": "2023",
    "month_to": "12",
    "year_to": "2024",
    "workflow_stage": "draft"
  }
}

You only need to include the fields you want to populate. Additional details like challenges, solutions, and contacts can be added afterwards.

Update an existing project

PUT https://<subdomain>.flowcase.com/api/v2/company/cv/customers/<customer_id>/projects/<project_id>

The request body uses the same company_project wrapper. Only include the fields you want to change.

Step 3: Enrich reference projects

Once a project exists, you can add structured details via separate endpoints. Each of these is optional and can be added incrementally. Reference Projects documents the endpoints for each one:

  • Project challenges: key challenges faced during the project
  • Project solutions: solutions implemented to address those challenges
  • Value propositions: business value and outcomes delivered to the customer
  • Skills: skills and competencies used or acquired during the project
  • Customer contacts: contact information, quotes, and testimonials (each with their own approval flags)
  • Project owners: Flowcase users who can edit the project without needing admin or reference manager roles
  • Project links: external resources related to the project
  • Custom tags: categorise projects with your own taxonomy
  • Offices: associate projects with specific offices or departments

Step 4: Publish the project

New projects are created with workflow_stage set to "draft" by default. When the project is ready to be visible to consultants, update the workflow stage:

PUT https://<subdomain>.flowcase.com/api/v2/company/cv/customers/<customer_id>/projects/<project_id>

{
  "company_project": {
    "workflow_stage": "live"
  }
}

The three workflow stages are:

Stage Description
draft Only visible to project owners and administrators.
ready_for_review Flagged for review before publishing.
live Visible to all users in the account.

When building an integration that runs on a schedule:

  1. Fetch customers from your source system and for each one:
    • Look up by external_unique_id in Flowcase.
    • If found, update the customer if any fields have changed.
    • If not found, create a new customer with the external_unique_id set.
  2. Fetch reference projects from your source system and for each one:
    • Look up by external_unique_id or search by project name.
    • If found, update the project if any fields have changed.
    • If not found, create a new project under the matching customer.
  3. Enrich projects with challenges, solutions, skills, and other details as needed.
  4. Handle deletions if your source system tracks removed projects. Note that you must delete all projects belonging to a customer before you can delete the customer itself.

Deleting records

Delete a project

DELETE https://<subdomain>.flowcase.com/api/v2/company/cv/customers/<customer_id>/projects/<project_id>

See Delete a reference project for the full call.

Delete a customer

Before deleting a customer, you must first delete all of its projects. You can list a customer's projects with List projects for a customer:

GET https://<subdomain>.flowcase.com/api/v2/company/cv/projects?company_customer_id=<customer_id>

Then delete each project before deleting the customer:

DELETE https://<subdomain>.flowcase.com/api/v2/company/cv/customers/<customer_id>

What's next