Custom Fields | VivreCRM API

List definitions

GET/api/v1/custom-field-definitions/

Response fields 10

idstring (uuid)
organisationstring (uuid)
entity_typestring
field_namestring
field_typeenum
is_requiredboolean
optionsarray of object
stateenum
name_clashobject
created_atstring (date-time)

curl "https://api.vivrecrm.com/api/v1/custom-field-definitions/" \
  -H "X-Api-Key: $VIVRE_API_KEY"

import os, requests

resp = requests.get(
    "https://api.vivrecrm.com/api/v1/custom-field-definitions/",
    headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())

const resp = await fetch("https://api.vivrecrm.com/api/v1/custom-field-definitions/", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.VIVRE_API_KEY,
  },
});
console.log(await resp.json());

Response 200

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "entity_type": "",
      "field_name": "",
      "field_type": "text",
      "is_required": true,
      "options": [],
      "state": "active",
      "name_clash": null,
      "created_at": "2026-10-17T09:30:00+05:30"
    }
  ]
}

Create definition

POST/api/v1/custom-field-definitions/

Body

entity_typestringRequired
field_namestringRequired
field_typeenumRequired: One of text, number, date, select, checkbox, email, url.
is_requiredboolean
optionsarray of object
confirm_orphansboolean

Response fields 10

idstring (uuid)
organisationstring (uuid)
entity_typestring
field_namestring
field_typeenum
is_requiredboolean
optionsarray of object
stateenum
name_clashobject
created_atstring (date-time)

curl -X POST "https://api.vivrecrm.com/api/v1/custom-field-definitions/" \
  -H "X-Api-Key: $VIVRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity_type": "", "field_name": "", "field_type": "text"}'

import os, requests

resp = requests.post(
    "https://api.vivrecrm.com/api/v1/custom-field-definitions/",
    headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
    json={
      "entity_type": "",
      "field_name": "",
      "field_type": "text"
    },
)
print(resp.json())

const resp = await fetch("https://api.vivrecrm.com/api/v1/custom-field-definitions/", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.VIVRE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "entity_type": "",
    "field_name": "",
    "field_type": "text"
  }),
});
console.log(await resp.json());

Response 201

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "entity_type": "",
  "field_name": "",
  "field_type": "text",
  "is_required": true,
  "options": [
    null
  ],
  "state": "active",
  "name_clash": null,
  "created_at": "2026-10-17T09:30:00+05:30"
}

List attribution field configs (the value lists admins customised)

GET/api/v1/attribution-field-config/

Response fields 4

idstring (uuid)
field_namestring
valuesarray of object
updated_atstring (date-time)

curl "https://api.vivrecrm.com/api/v1/attribution-field-config/" \
  -H "X-Api-Key: $VIVRE_API_KEY"

import os, requests

resp = requests.get(
    "https://api.vivrecrm.com/api/v1/attribution-field-config/",
    headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())

const resp = await fetch("https://api.vivrecrm.com/api/v1/attribution-field-config/", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.VIVRE_API_KEY,
  },
});
console.log(await resp.json());

Response 200

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "field_name": "",
      "values": [],
      "updated_at": "2026-10-17T09:30:00+05:30"
    }
  ]
}

Create an attribution field config

POST/api/v1/attribution-field-config/

Body

field_namestringRequired
valuesarray of object

Response fields 4

idstring (uuid)
field_namestring
valuesarray of object
updated_atstring (date-time)

curl -X POST "https://api.vivrecrm.com/api/v1/attribution-field-config/" \
  -H "X-Api-Key: $VIVRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"field_name": ""}'

import os, requests

resp = requests.post(
    "https://api.vivrecrm.com/api/v1/attribution-field-config/",
    headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
    json={
      "field_name": ""
    },
)
print(resp.json())

const resp = await fetch("https://api.vivrecrm.com/api/v1/attribution-field-config/", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.VIVRE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "field_name": ""
  }),
});
console.log(await resp.json());

Response 201

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "field_name": "",
  "values": [
    null
  ],
  "updated_at": "2026-10-17T09:30:00+05:30"
}

Replace one field's whole value list, creating the config if needed

PUT/api/v1/attribution-field-config/upsert/

Body

field_nameenumRequired: The field whose value list this is: a lead attribution field (source, medium, channel, platform, priority, campaign), the lead status, or the company's company_type. One of source, medium, channel, platform, priority, campaign, status, company_type.
valuesarray of string: Ordered option list. For status and company_type it must be non-empty with no blanks.

Response fields 4

idstring (uuid)
field_namestring
valuesarray of object
updated_atstring (date-time)

curl -X PUT "https://api.vivrecrm.com/api/v1/attribution-field-config/upsert/" \
  -H "X-Api-Key: $VIVRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"field_name": "source"}'

import os, requests

resp = requests.put(
    "https://api.vivrecrm.com/api/v1/attribution-field-config/upsert/",
    headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
    json={
      "field_name": "source"
    },
)
print(resp.json())

const resp = await fetch("https://api.vivrecrm.com/api/v1/attribution-field-config/upsert/", {
  method: "PUT",
  headers: {
    "X-Api-Key": process.env.VIVRE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "field_name": "source"
  }),
});
console.log(await resp.json());

Response 200

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "field_name": "",
  "values": [
    null
  ],
  "updated_at": "2026-10-17T09:30:00+05:30"
}

Retrieve an attribution field config

GET/api/v1/attribution-field-config/{public_id}/

Parameters

public_idpath, stringRequired

Response fields 4

idstring (uuid)
field_namestring
valuesarray of object
updated_atstring (date-time)

curl "https://api.vivrecrm.com/api/v1/attribution-field-config/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
  -H "X-Api-Key: $VIVRE_API_KEY"

import os, requests

resp = requests.get(
    "https://api.vivrecrm.com/api/v1/attribution-field-config/7c9e6679-7425-40de-944b-e07fc1f90ae7/",
    headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())

const resp = await fetch("https://api.vivrecrm.com/api/v1/attribution-field-config/7c9e6679-7425-40de-944b-e07fc1f90ae7/", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.VIVRE_API_KEY,
  },
});
console.log(await resp.json());

Response 200

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "field_name": "",
  "values": [
    null
  ],
  "updated_at": "2026-10-17T09:30:00+05:30"
}

Replace an attribution field config

PUT/api/v1/attribution-field-config/{public_id}/

Parameters

public_idpath, stringRequired

Body

field_namestringRequired
valuesarray of object

Response fields 4

idstring (uuid)
field_namestring
valuesarray of object
updated_atstring (date-time)

curl -X PUT "https://api.vivrecrm.com/api/v1/attribution-field-config/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
  -H "X-Api-Key: $VIVRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"field_name": ""}'

import os, requests

resp = requests.put(
    "https://api.vivrecrm.com/api/v1/attribution-field-config/7c9e6679-7425-40de-944b-e07fc1f90ae7/",
    headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
    json={
      "field_name": ""
    },
)
print(resp.json())

const resp = await fetch("https://api.vivrecrm.com/api/v1/attribution-field-config/7c9e6679-7425-40de-944b-e07fc1f90ae7/", {
  method: "PUT",
  headers: {
    "X-Api-Key": process.env.VIVRE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "field_name": ""
  }),
});
console.log(await resp.json());

Response 200

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "field_name": "",
  "values": [
    null
  ],
  "updated_at": "2026-10-17T09:30:00+05:30"
}

Update an attribution field config

PATCH/api/v1/attribution-field-config/{public_id}/

Parameters

public_idpath, stringRequired

Body

field_namestringRequired
valuesarray of object

Response fields 4

idstring (uuid)
field_namestring
valuesarray of object
updated_atstring (date-time)

curl -X PATCH "https://api.vivrecrm.com/api/v1/attribution-field-config/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
  -H "X-Api-Key: $VIVRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"field_name": ""}'

import os, requests

resp = requests.patch(
    "https://api.vivrecrm.com/api/v1/attribution-field-config/7c9e6679-7425-40de-944b-e07fc1f90ae7/",
    headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
    json={
      "field_name": ""
    },
)
print(resp.json())

const resp = await fetch("https://api.vivrecrm.com/api/v1/attribution-field-config/7c9e6679-7425-40de-944b-e07fc1f90ae7/", {
  method: "PATCH",
  headers: {
    "X-Api-Key": process.env.VIVRE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "field_name": ""
  }),
});
console.log(await resp.json());

Response 200

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "field_name": "",
  "values": [
    null
  ],
  "updated_at": "2026-10-17T09:30:00+05:30"
}

Delete an attribution field config (back to the seeded values)

DELETE/api/v1/attribution-field-config/{public_id}/

Parameters

public_idpath, stringRequired

curl -X DELETE "https://api.vivrecrm.com/api/v1/attribution-field-config/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
  -H "X-Api-Key: $VIVRE_API_KEY"

import os, requests

resp = requests.delete(
    "https://api.vivrecrm.com/api/v1/attribution-field-config/7c9e6679-7425-40de-944b-e07fc1f90ae7/",
    headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.status_code)

const resp = await fetch("https://api.vivrecrm.com/api/v1/attribution-field-config/7c9e6679-7425-40de-944b-e07fc1f90ae7/", {
  method: "DELETE",
  headers: {
    "X-Api-Key": process.env.VIVRE_API_KEY,
  },
});
console.log(resp.status);

Replace a custom field definition

PUT/api/v1/custom-field-definitions/{public_id}/

Parameters

public_idpath, stringRequired

Body

entity_typestringRequired
field_namestringRequired
field_typeenumRequired: One of text, number, date, select, checkbox, email, url.
is_requiredboolean
optionsarray of object
confirm_orphansboolean

Response fields 10

idstring (uuid)
organisationstring (uuid)
entity_typestring
field_namestring
field_typeenum
is_requiredboolean
optionsarray of object
stateenum
name_clashobject
created_atstring (date-time)

curl -X PUT "https://api.vivrecrm.com/api/v1/custom-field-definitions/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
  -H "X-Api-Key: $VIVRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity_type": "", "field_name": "", "field_type": "text"}'

import os, requests

resp = requests.put(
    "https://api.vivrecrm.com/api/v1/custom-field-definitions/7c9e6679-7425-40de-944b-e07fc1f90ae7/",
    headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
    json={
      "entity_type": "",
      "field_name": "",
      "field_type": "text"
    },
)
print(resp.json())

const resp = await fetch("https://api.vivrecrm.com/api/v1/custom-field-definitions/7c9e6679-7425-40de-944b-e07fc1f90ae7/", {
  method: "PUT",
  headers: {
    "X-Api-Key": process.env.VIVRE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "entity_type": "",
    "field_name": "",
    "field_type": "text"
  }),
});
console.log(await resp.json());

Response 200

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "entity_type": "",
  "field_name": "",
  "field_type": "text",
  "is_required": true,
  "options": [
    null
  ],
  "state": "active",
  "name_clash": null,
  "created_at": "2026-10-17T09:30:00+05:30"
}

Update a custom field definition (name, options, visibility)

PATCH/api/v1/custom-field-definitions/{public_id}/

Parameters

public_idpath, stringRequired

Body

entity_typestringRequired
field_namestringRequired
field_typeenumRequired: One of text, number, date, select, checkbox, email, url.
is_requiredboolean
optionsarray of object
confirm_orphansboolean

Response fields 10

idstring (uuid)
organisationstring (uuid)
entity_typestring
field_namestring
field_typeenum
is_requiredboolean
optionsarray of object
stateenum
name_clashobject
created_atstring (date-time)

curl -X PATCH "https://api.vivrecrm.com/api/v1/custom-field-definitions/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
  -H "X-Api-Key: $VIVRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity_type": "", "field_name": "", "field_type": "text"}'

import os, requests

resp = requests.patch(
    "https://api.vivrecrm.com/api/v1/custom-field-definitions/7c9e6679-7425-40de-944b-e07fc1f90ae7/",
    headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
    json={
      "entity_type": "",
      "field_name": "",
      "field_type": "text"
    },
)
print(resp.json())

const resp = await fetch("https://api.vivrecrm.com/api/v1/custom-field-definitions/7c9e6679-7425-40de-944b-e07fc1f90ae7/", {
  method: "PATCH",
  headers: {
    "X-Api-Key": process.env.VIVRE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "entity_type": "",
    "field_name": "",
    "field_type": "text"
  }),
});
console.log(await resp.json());

Response 200

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "entity_type": "",
  "field_name": "",
  "field_type": "text",
  "is_required": true,
  "options": [
    null
  ],
  "state": "active",
  "name_clash": null,
  "created_at": "2026-10-17T09:30:00+05:30"
}

Delete a custom field definition and its values

DELETE/api/v1/custom-field-definitions/{public_id}/

Parameters

public_idpath, stringRequired

curl -X DELETE "https://api.vivrecrm.com/api/v1/custom-field-definitions/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
  -H "X-Api-Key: $VIVRE_API_KEY"

import os, requests

resp = requests.delete(
    "https://api.vivrecrm.com/api/v1/custom-field-definitions/7c9e6679-7425-40de-944b-e07fc1f90ae7/",
    headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.status_code)

const resp = await fetch("https://api.vivrecrm.com/api/v1/custom-field-definitions/7c9e6679-7425-40de-944b-e07fc1f90ae7/", {
  method: "DELETE",
  headers: {
    "X-Api-Key": process.env.VIVRE_API_KEY,
  },
});
console.log(resp.status);

Move stored values to new options after an option edit

POST/api/v1/custom-field-definitions/{public_id}/migrate-values/

Parameters

public_idpath, stringRequired

Body

on_failureenum: What to do with a value the new type will not take: empty leaves the record with no value, default stores default instead, add_option adds the value to the options (select fields only), and abort changes nothing at all and answers 400 when any value will not convert. One of empty, default, add_option, abort.
defaultobject: Value stored for unconvertible values when on_failure=default; coerced to the field's type first. Any JSON type.

Response fields 5

migratedinteger
lossyinteger
failedinteger
blankinteger
added_optionsarray of string: Options appended to the select list (on_failure=add_option).

curl -X POST "https://api.vivrecrm.com/api/v1/custom-field-definitions/7c9e6679-7425-40de-944b-e07fc1f90ae7/migrate-values/" \
  -H "X-Api-Key: $VIVRE_API_KEY"

import os, requests

resp = requests.post(
    "https://api.vivrecrm.com/api/v1/custom-field-definitions/7c9e6679-7425-40de-944b-e07fc1f90ae7/migrate-values/",
    headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())

const resp = await fetch("https://api.vivrecrm.com/api/v1/custom-field-definitions/7c9e6679-7425-40de-944b-e07fc1f90ae7/migrate-values/", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.VIVRE_API_KEY,
  },
});
console.log(await resp.json());

Response 200

{
  "migrated": 1,
  "lossy": 1,
  "failed": 1,
  "blank": 1,
  "added_options": [
    ""
  ]
}

Which stored values would survive a change of type

GET/api/v1/custom-field-definitions/{public_id}/retype-preview/

Parameters

public_idpath, stringRequired

Response fields 5

totalinteger: Records holding a key for the field.
cleaninteger: Values that convert without change.
blankinteger: Records whose stored value is null or empty.
lossyarray of object
failedarray of object

curl "https://api.vivrecrm.com/api/v1/custom-field-definitions/7c9e6679-7425-40de-944b-e07fc1f90ae7/retype-preview/" \
  -H "X-Api-Key: $VIVRE_API_KEY"

import os, requests

resp = requests.get(
    "https://api.vivrecrm.com/api/v1/custom-field-definitions/7c9e6679-7425-40de-944b-e07fc1f90ae7/retype-preview/",
    headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())

const resp = await fetch("https://api.vivrecrm.com/api/v1/custom-field-definitions/7c9e6679-7425-40de-944b-e07fc1f90ae7/retype-preview/", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.VIVRE_API_KEY,
  },
});
console.log(await resp.json());

Response 200

{
  "total": 1,
  "clean": 1,
  "blank": 1,
  "lossy": [
    {
      "record_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "value": null,
      "becomes": ""
    }
  ],
  "failed": [
    {
      "record_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "value": null,
      "reason": ""
    }
  ]
}

Change a custom field's type

POST/api/v1/custom-field-definitions/{public_id}/retype/

Parameters

public_idpath, stringRequired

Body

field_typeenumRequired: The new type. Must differ from the current one. One of text, number, date, select, checkbox, email, url.
optionsarray of string: Required (non-empty) when field_type is select.

Response fields 10

idstring (uuid)
organisationstring (uuid)
entity_typestring
field_namestring
field_typeenum
is_requiredboolean
optionsarray of object
stateenum
name_clashobject
created_atstring (date-time)

curl -X POST "https://api.vivrecrm.com/api/v1/custom-field-definitions/7c9e6679-7425-40de-944b-e07fc1f90ae7/retype/" \
  -H "X-Api-Key: $VIVRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"field_type": "text"}'

import os, requests

resp = requests.post(
    "https://api.vivrecrm.com/api/v1/custom-field-definitions/7c9e6679-7425-40de-944b-e07fc1f90ae7/retype/",
    headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
    json={
      "field_type": "text"
    },
)
print(resp.json())

const resp = await fetch("https://api.vivrecrm.com/api/v1/custom-field-definitions/7c9e6679-7425-40de-944b-e07fc1f90ae7/retype/", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.VIVRE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "field_type": "text"
  }),
});
console.log(await resp.json());

Response 201

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "entity_type": "",
  "field_name": "",
  "field_type": "text",
  "is_required": true,
  "options": [
    null
  ],
  "state": "active",
  "name_clash": null,
  "created_at": "2026-10-17T09:30:00+05:30"
}

Put an entity's active custom fields in the order forms show them

POST/api/v1/custom-field-definitions/reorder/

Body

entity_typestringRequired
orderarray of string (uuid)Required

Response fields 1

orderarray of string (uuid): The field ids as sent, now in position order.

Can also return 400.

curl -X POST "https://api.vivrecrm.com/api/v1/custom-field-definitions/reorder/" \
  -H "X-Api-Key: $VIVRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity_type": "", "order": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"]}'

import os, requests

resp = requests.post(
    "https://api.vivrecrm.com/api/v1/custom-field-definitions/reorder/",
    headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
    json={
      "entity_type": "",
      "order": [
        "7c9e6679-7425-40de-944b-e07fc1f90ae7"
      ]
    },
)
print(resp.json())

const resp = await fetch("https://api.vivrecrm.com/api/v1/custom-field-definitions/reorder/", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.VIVRE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "entity_type": "",
    "order": [
      "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    ]
  }),
});
console.log(await resp.json());

Response 200

{
  "order": [
    "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  ]
}