{"templateId":"../@theme/Templates/BlogWithAuthors","sharedDataIds":{"sidebar":"sidebar-blog/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Why this matters","description":"Developer documentation for the Caraer platform. REST API reference, Bearer authentication, tutorials, and guides for records, forms, webpages, webhooks, and automations.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide explains how to create, update, and manage records through the"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v2/records"]}," endpoints."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"why-this-matters","__idx":0},"children":["Why this matters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Records are the actual data instances for your objects (for example candidates,"," ","vacancies, companies). These endpoints gives you a complete lifecycle:"," ","create/update, search, relation handling, archive/restore, and morphing."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Bearer token or API Token with permissions for the relevant object scopes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Object internal name (used as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{objectName}"]}," in routes)"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"endpoint-map","__idx":2},"children":["Endpoint map"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Core write and lifecycle endpoints:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v2/records/{objectName}"]}," create a record"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /api/v2/records/{objectName}/{uuid}"]}," update a record"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v2/records/{objectName}/createOrUpdate"]}," upsert by unique fields"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /api/v2/records/{uuid}"]}," archive, anonymize, or hard delete"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v2/records/{uuid}/restore"]}," restore archived records"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v2/records/{uuid}/morph"]}," move/add visibility across objects"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List/search and projection endpoints:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v2/records/index"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v2/records/search"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v2/records/{uuid}"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v2/records/{uuid}/previews/{name}"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Relation endpoints:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v2/records/relations/{fromUuid}/{relationName}/{toUuid}"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /api/v2/records/relations/{fromUuid}/{relationName}/{toUuid}"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-create-a-record","__idx":3},"children":["Step 1: Create a record"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://your-company.caraer.com/api/v2/records/candidate?parse=true\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"properties\": {\n      \"firstname\": \"Jane\",\n      \"lastname\": \"Doe\",\n      \"email\": \"jane.doe@example.com\"\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["What happens:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The controller builds a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Record"]}," from your DTO and object name."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Property-level validation is applied in record services."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You get a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CreateResponse"]}," with the created record."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["When setting parse to true the values will be parsed to labels and human readable values. Leave parse out if you want the internal values when working on an integration for example. Parse is by default false."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-update-a-record","__idx":4},"children":["Step 2: Update a record"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X PUT \"https://your-company.caraer.com/api/v2/records/candidate/RECORD_UUID?parse=true\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"properties\": {\n      \"application_status\": \"in_progress\"\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The endpoint returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UpdateResponse<Record>"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-use-create-or-update-for-idempotent-integrations","__idx":5},"children":["Step 3: Use create-or-update for idempotent integrations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your integration receives repeated events, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createOrUpdate"]}," is usually the"," ","safest write pattern:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://your-company.caraer.com/api/v2/records/candidate/createOrUpdate\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"values\": {\n      \"email\": \"jane.doe@example.com\",\n      \"firstname\": \"Jane\",\n      \"lastname\": \"Doe\"\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a matching unique record exists, Caraer updates it; otherwise it creates a"," ","new one. The matching is based on all the unique properties of a record."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-to-submit-values-by-property-type-and-format","__idx":6},"children":["How to submit values by property type and format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you submit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["values"]},", the backend validates by ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["property type"]}," and uses"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["property format"]}," for parsing/formatting behavior. The key is always the"," ","property ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}," of the property, and the value shape must match the type."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common type rules from backend validation:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]},": send a string"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["number"]},": send a numeric value (for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["120000"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"120000\""]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["date"]},": send unix timestamp milliseconds in UTC (preferred). ISO date/date-time"," ","inputs are also accepted by date parsing and normalized"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkbox"]},": send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," (or string ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"true\""]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"false\""]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["single-select"]},": send one option name exactly as configured"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["multi-select"]},": send option names as one semicolon-separated string or as an array of the names"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tag"]},": send tags as one semicolon-separated string or as an array of the names"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["range"]},": send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"min;max\""]}," (both numeric)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["structure"]},": send a valid JSON string (not a raw nested JSON object)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["file"]},": send a file key string (needs to be under your company files path)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["linked-property"]},": do not send a value (backend rejects manual values since they're read only and managed on the related records)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example payload covering multiple types:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"properties\": {\n    \"firstname\": \"Jane Doe\",\n    \"salary\": 4200,\n    \"start_date\": 1742851200000, // \"2025-04-24T00:00:00.000Z\"\n    \"available_remote\": true,\n    \"application_status\": \"in_progress\",\n    \"skills\": \"java;spring;neo4j\", // ['java', 'spring', 'neo4j']\n    \"labels\": \"high_priority;backend\", // ['high_priority', 'backend']\n    \"salary_range\": \"3500;5000\",\n    \"profile_data\": \"{\\\"github\\\":\\\"janedoe\\\",\\\"years_experience\\\":6}\",\n    \"resume_file\": \"COMPANY_UUID/files/candidates/jane-doe-cv.pdf\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"type-vs-format-important-distinction","__idx":7},"children":["Type vs format (important distinction)"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Type"]}," controls what value shape is valid."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Format"]}," controls how that value is interpreted or displayed."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example: a string property may accept multiple string input styles, but the"," ","normalized stored value is still validated as a string type value."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"submission-checklist-before-calling-createupdate","__idx":8},"children":["Submission checklist before calling create/update"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm property ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}," keys match the object schema exactly."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm select values exist in property options."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["multi-select"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tag"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["range"]},", use semicolon delimiters or arrays with names of the options."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["structure"]},", serialize to a JSON string first."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not send values for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["linked-property"]}," fields."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-list-records-for-ui-and-automation","__idx":9},"children":["Step 4: List records for UI and automation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/index"]}," for generic pagination, with optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["archived=true"]}," and"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parse=true"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note on archived records:"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["archived"]}," query parameter determines whether to fetch archived (soft-deleted) records or not. By default, only active (non-archived) records are returned (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["archived=false"]},")."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["archived=true"]}," to list only records that have been archived."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Omitting this parameter (or setting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["archived=false"]},") will fetch only currently active records."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example:"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"To fetch only archived records, use:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://your-company.caraer.com/api/v2/records/OBJECT_NAME/index?archived=true\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-connect-records-with-relations","__idx":10},"children":["Step 5: Connect records with relations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use these endpoints to link two existing records with a named relation."," ","The route is:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v2/records/relations/{fromUuid}/{relationName}/{toUuid}"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /api/v2/records/relations/{fromUuid}/{relationName}/{toUuid}"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-a-relation-between-two-records","__idx":11},"children":["Create a relation between two records"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example: link candidate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FROM_UUID"]}," to vacancy ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TO_UUID"]}," using relation"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["applied_for"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://your-company.caraer.com/api/v2/records/relations/FROM_UUID/applied_for/TO_UUID?primary=true\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["What happens on create:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Backend loads both records and the relation by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["relationName"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If one of them does not exist, the request fails with a not-found error."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The relation direction is resolved against relation schema (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["from"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to"]},") in"," ","backend logic, so use the relation name exactly as defined."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The relation is merged (created if missing, updated if already present)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"delete-a-relation-between-two-records","__idx":12},"children":["Delete a relation between two records"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This removes the relation edge between those record UUIDs for that relation"," ","name."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X DELETE \"https://your-company.caraer.com/api/v2/records/relations/FROM_UUID/applied_for/TO_UUID\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["What happens on delete:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["It checks relation delete access on both involved objects."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["It deletes matching relation edge(s) for that relation between the two UUIDs."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-primary-works-for-relations","__idx":13},"children":["How ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primary"]}," works for relations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primary"]}," is a query parameter on relation creation:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primary=false"]}," (default): creates/updates the relation without primary"," ","selection behavior."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primary=true"]},": marks this specific relation edge as the primary one."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Important primary behavior:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The created relation gets ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primary = true"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For the same relation type and same target record (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["toUuid"]},"), other incoming"," ","relation edges are set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primary = false"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Practical result: you can enforce a single \"main\" linked record for a target"," ","record within that relation type."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://your-company.caraer.com/api/v2/records/relations/CANDIDATE_UUID/applied_for/VACANCY_UUID?primary=true\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"primary-vs-primary_object-do-not-confuse-these","__idx":14},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primary"]}," vs ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primary_object"]}," (do not confuse these)"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Relation ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primary"]}," is metadata on a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["relation edge"]}," between two records."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primary_object"]}," is metadata on the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["record node itself"]}," and represents that"," ","record's main object context."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["They solve different problems and are managed separately."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-6-handle-record-lifecycle-safely","__idx":15},"children":["Step 6: Handle record lifecycle safely"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Delete modes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["archive"]}," (default): soft delete sets the deletedAt property on the record"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["anonymize"]},": removes most data values from the record, preserving only its structure in the database (useful for keeping references to submissions or campaign aggregates while ensuring privacy)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delete"]},": Permanently removes the record from the database (hard delete). Once deleted, the record cannot be recovered."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X DELETE \"https://your-company.caraer.com/api/v2/records/RECORD_UUID?mode=archive\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Restore:"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," The restore endpoint (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v2/records/{uuid}/restore"]},") can only fully restore records that were ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["archived"]}," (soft deleted)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["While you can technically call restore for records deleted with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["anonymize"]},", most data values will ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," be recovered because they were irreversibly anonymized. Only records deleted with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["archive"]}," (soft delete) mode can be restored with their original data intact."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://your-company.caraer.com/api/v2/records/RECORD_UUID/restore\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-7-morph-records-across-objects","__idx":16},"children":["Step 7: Morph records across objects"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Morphing lets one record be visible in other object contexts without"," ","duplicating data. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/blog/2026-06-07-object-morph-explained"},"children":["Object morph explained"]}," ","for primary object vs morph objects, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["extendsTo"]},", and the"," ","person → contact/candidate pattern."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://your-company.caraer.com/api/v2/records/RECORD_UUID/morph\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"objects\": [\n      { \"name\": \"candidate\" },\n      { \"name\": \"lead\" }\n    ]\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-implementation-notes","__idx":17},"children":["Common implementation notes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["update"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createOrUpdate"]}," all support ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parse=true"]}," query"," ","parsing for returned values."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/search"]}," can return either full records or previews depending on request"," ","payload."]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Important:"]}," Build integrations around validated property names and object"," ","names from your environment, not hardcoded assumptions from examples."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-reading","__idx":18},"children":["Related reading"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/blog/2026-06-07-object-morph-explained"},"children":["Object morph explained"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/blog/2026-03-25-submit-forms-and-embed-on-your-website"},"children":["Submitting forms and embedding forms on your website"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/blog/2026-03-25-caraer-data-model-object-property-relation"},"children":["Caraer data model: Object, Property, Relation"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/get-started"},"children":["API introduction"]}]}]}]},"headings":[{"value":"Why this matters","id":"why-this-matters","depth":2},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Endpoint map","id":"endpoint-map","depth":2},{"value":"Step 1: Create a record","id":"step-1-create-a-record","depth":2},{"value":"Step 2: Update a record","id":"step-2-update-a-record","depth":2},{"value":"Step 3: Use create-or-update for idempotent integrations","id":"step-3-use-create-or-update-for-idempotent-integrations","depth":2},{"value":"How to submit values by property type and format","id":"how-to-submit-values-by-property-type-and-format","depth":2},{"value":"Type vs format (important distinction)","id":"type-vs-format-important-distinction","depth":3},{"value":"Submission checklist before calling create/update","id":"submission-checklist-before-calling-createupdate","depth":3},{"value":"Step 4: List records for UI and automation","id":"step-4-list-records-for-ui-and-automation","depth":2},{"value":"Step 5: Connect records with relations","id":"step-5-connect-records-with-relations","depth":2},{"value":"Create a relation between two records","id":"create-a-relation-between-two-records","depth":3},{"value":"Delete a relation between two records","id":"delete-a-relation-between-two-records","depth":3},{"value":"How primary works for relations","id":"how-primary-works-for-relations","depth":3},{"value":"primary vs primary_object (do not confuse these)","id":"primary-vs-primary_object-do-not-confuse-these","depth":3},{"value":"Step 6: Handle record lifecycle safely","id":"step-6-handle-record-lifecycle-safely","depth":2},{"value":"Step 7: Morph records across objects","id":"step-7-morph-records-across-objects","depth":2},{"value":"Common implementation notes","id":"common-implementation-notes","depth":2},{"value":"Related reading","id":"related-reading","depth":2}],"frontmatter":{"title":"Save records","authors":["sem_tadema"],"tags":["documentation","api"],"template":"../@theme/Templates/BlogWithAuthors","seo":{"title":"Why this matters"}},"lastModified":"2026-06-07T14:02:22.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/blog/2026-03-25-save-records","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}