Proposals

Proposals give you a way to collect and tailor copies of selected CVs (résumés) and projects, and export them using our templating system.

Admin level API users can access all proposals in your account.

The calls below use /api/v1/all_offers, /api/v1/offers and /api/v2/offers. Use the path shown for each endpoint.

Look up proposals

List proposals

GET https://<subdomain>.flowcase.com/api/v1/all_offers?query=<proposal_name_query>&include_archived=false&limit=<limit>&offset=<offset>

The include_archived parameter determines whether archived proposals are returned. Specifying the query parameter will limit the results to those where the name partially matches the parameter value.

These results are paginated, with a maximum limit of 100. Use offset=100 to skip the first hundred and get the next limit proposals, and so on.

Note the endpoint used here is /all_offers. You can query the /offers endpoint for this as well, but that only works for some user types, and only returns proposals where the user is a contributor or owner.

Response:

[
  {
    "_id": "PROPOSAL_ID",
    "name": "Name",
    "archived": false,
    "created_at": "2020-07-19T10:20:40.718Z",
    "updated_at": "2020-07-19T10:20:40.718Z",
    "owner_id": "USER_ID",
    "owner_name": "User name",
    "api_owner_id": null,
    "api_owner_name": null,
    "status": "initial"
    // some fields omitted
  }
  // more proposals
]

Find a proposal by id

GET https://<subdomain>.flowcase.com/api/v1/offers/<proposal_id>

Response:

{
  "_id": "PROPOSAL_ID",
  "name": "Name",
  "archived": false,
  "created_at": "2020-07-19T10:20:40.718Z",
  "updated_at": "2020-07-19T10:20:40.718Z",
  "owner_id": "USER_ID",
  "owner_name": "User name",
  "api_owner_id": null,
  "api_owner_name": null,
  "status": "initial"
  // some fields omitted
}

Manage proposals

Create and update proposals over the API. This lets you start new proposals automatically from actions in other systems or workflows, and manage them over time.

Create a proposal

POST https://<subdomain>.flowcase.com/api/v2/offers/

Request body:

The request body should contain the name of the proposal and optionally either an owner_id or api_owner_id field which will set the owner of the proposal. If no owner is provided it will default to the current API user.

{
  "offer": {
    "name": "Example",
    "owner_id": "OWNER_ID", // optional
    "api_owner_id": "API_OWNER_ID", // optional
    "status": "editing" // optional, defaults to "initial"
  }
}

Response:

{
  "_id": "PROPOSAL_ID",
  "name": "Example",
  "archived": false,
  "created_at": "2020-06-24T12:06:04.390Z",
  "updated_at": "2020-06-24T12:06:04.458Z",
  "owner_id": null,
  "owner_name": null,
  "api_owner_id": "ID",
  "api_owner_name": null,
  "status": "editing"
  // some fields omitted...
}

Update a proposal

PUT https://<subdomain>.flowcase.com/api/v1/offers/<proposal_id>

Request body:

You can change the name or archive a proposal using an update request. Only specify the field you want to change.

{
  "offer": {
    "name": "New name", // optional
    "archived": true, // optional
    "status": "finalised" // optional
  }
}

Change the owner

Change the owner of the proposal. The owner can be a user or an API user.

PUT https://<subdomain>.flowcase.com/api/v2/offers/<proposal_id>/owner

Request body:

type should be user or api_user.

{
  "owner": {
    "type": "user",
    "id": "USER_ID"
  }
}

Collaborators

List collaborators on a proposal

GET https://<subdomain>.flowcase.com/api/v2/offers/<proposal_id>/collaborators

Response:

{
  "api_users": [
    {
      "id": "<api_user_id>",
      "name": "<name>",
      "access_token": "<token>",
      "enabled": true,
      "roles": ["readonly_proposal"]
      // ... some fields omitted
    }
    // ... more api users
  ],
  "users": [
    {
      "id": "<user_id>",
      "email": "<email>",
      "external_unique_id": "<external_unique_id>",
      "office_id": "<office_id>",
      "office_name": "<office_name>",
      "country_id": "<country_id>",
      "image": {
        // image urls
      },
      "name": "<name>",
      "default_cv_id": "<cv_id>"
      // ... some fields omitted
    }
    // ... more users
  ]
}

Add a collaborator to the proposal

POST https://<subdomain>.flowcase.com/api/v2/offers/<proposal_id>/collaborators

Request body:

{
  "collaborator": {
    "type": "user",
    "id": "USER_ID"
  }
}

Remove a collaborator from the proposal

collaborator_type should be user or api_user.

DELETE https://<subdomain>.flowcase.com/api/v2/offers/<proposal_id>/collaborators/<collaborator_type>/<collaborator_id>

Tailored CVs (résumés)

Add a CV (résumé) to a proposal

When you add a CV (résumé) to a proposal you create a copy of the Master CV (résumé) which can be tailored to the proposal. The tailored CV (résumé) can then be edited using the CV (résumé) API without affecting the Master CV (résumé).

POST https://<subdomain>.flowcase.com/api/v1/offers/<proposal_id>/cvs

Request body:

{
  "cv": {
    "cv_id": "CV_ID"
  }
}

Remove a CV (résumé) from a proposal

To remove a tailored CV (résumé) from a proposal, issue a DELETE request.

DELETE https://<subdomain>.flowcase.com/api/v1/offers/<proposal_id>/cvs/<tailored_cv_id>

List CVs (résumés) on a proposal

GET https://<subdomain>.flowcase.com/api/v1/offers/<proposal_id>/cvs

Response:

[
  {
    "id": "TAILORED_CV_ID",
    "user_id": "USER_ID",
    "status": "initial"
    // rest of fields same structure as for master CVs
  }
  // More tailored CVs
]

Reference projects in a proposal

Add a reference project to a proposal

When you add a reference to a proposal you create a copy of the reference project which can be tailored to the proposal. The tailored version can then be edited using the reference project endpoints. See Update a reference project.

POST https://<subdomain>.flowcase.com/api/v1/offers/<proposal_id>/references

Request body:

{
  "reference": {
    "company_customer_id": "CUSTOMER_ID", //required
    "company_project_id": "REFERENCE_ID" //required
  }
}

Remove a reference project from a proposal

To remove a tailored reference project from a proposal, issue a DELETE request.

DELETE https://<subdomain>.flowcase.com/api/v1/offers/<proposal_id>/references/<tailored_reference_id>

List reference projects on a proposal

GET https://<subdomain>.flowcase.com/api/v1/offers/<proposal_id>/references

Response:

[
  {
    "id": "TAILORED_REFERENCE_ID",
    "status": "initial"
    // rest of fields same structure as for reference projects
  }
  // More tailored reference projects
]

Link to a proposal on the website

You can create a link to a proposal from another application, for example by creating clickable links or buttons to take the user directly to the specific proposal in Flowcase. To do this, you need to know the proposal ID and the subdomain of your Flowcase account, and construct the URL as follows:

https://<subdomain>.flowcase.com/redirect/to/proposal?id=<proposal_id>

Statuses

Track the readiness of proposals and their components (résumés/CVs and reference projects) using standardised status values. These statuses can be managed via the API and are visible in the Flowcase app.

Status labels help teams collaborate by showing proposal readiness, so several stakeholders can coordinate. They also enable integration with other systems, for example triggering automated workflows when a proposal reaches "Ready to Submit" status.

Proposal status

API Value	UI Display	Description
initial	Selecting resources	Profiles/projects are still being added to the proposal. (default)
editing	Tailoring	Profiles/projects within the proposal are being tailored.
finalised	Ready to submit	All profiles/projects have been tailored and the proposal is ready.
submitted	Submitted	The proposal has been submitted (outside of Flowcase). Equivalent to marking a proposal as done.
won	Won	The proposal was successful and the business was secured.
lost	Lost	The proposal was unsuccessful.

Proposal status can be read and set via the API when creating or updating a proposal, field status. If no status is provided, it defaults to initial.

Résumé (CV) and project status

API Value	UI Display	Description
initial	Added	The profile/project has been added to a proposal. (default)
editing	Tailoring	The profile/project is being tailored.
finalised	Ready	The profile/project is tailored and ready for submission.
null	Unknown	Status is either explicitly set to null via the API or the proposal was created before statuses were introduced.

The status of a tailored résumé (CV) or reference project can be read via the API but not changed.