Creates a record and, in the same step, links it to other records. If one link fails, nothing is created. The change is saved in the record’s history under your name.
- Changes data: yes
- Who can use it: Your role’s rights on that object in the “Entities” group of the role: “Create”.
What it is for
- Create a shipment with route and cargo in one request. See Freight Procurement.
- Add a carrier to your network or invite one, without duplicates. See Carrier Network.
- Add a location. See Locations.
- Add trucks and drivers and link them. See Fleets.
- Add a record to your data model, with links. See Data models.
Example prompts
- “Create a shipment from Kyiv to Lviv, loading on Monday 09:00 to 17:00, delivery on Tuesday 09:00 to 17:00, 20 t, curtainsider.”
- “Add truck DEMO-FL-003, tractor, curtainsider, 22 t, and driver Demo: Petro on it.”
- “Add a request Odesa → Dnipro to Demo: Shipment request, loading on November 25.”
Good to know
- A carrier already in your network is not added twice: the answer returns it with
matched_existing. A carrier needs an email or a phone.approvedadds the carrier as “Confirmed” without an invitation,notify: falsesends no email,on_existingsays what to do with a carrier that is found. - A shipment is created as a draft with defaults for what you leave out: who can bid, auction length, bid rules and step from your brand’s tender settings (open to your carrier network, 120 minutes, any bids allowed when not set), a point window of 8 hours.
- Shipment
auction_time: 30 to 1,440 minutes. - A shipment needs
country_id(lowercase, such asua) and at least twowaypoints. Give every point its date. Weight is in kilograms. - A location you already have is not created twice: Cargofy returns the existing location. Check its address in the answer.
- A location needs
name,address_1,city,state,postal_code,country_id,latandlng. One location by its address is added withfacilities-import.
Reference
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
entity | string | yes | The object, as entities-list names it. |
fields | object | yes | Field values. entities-schema shows the fields and what each expects. Cannot be empty. |
reasoning | string | no | Why the record is created. |
links | array | no | Links to other records. Each: relationship_id and target_record_id. |
Returns
The created record.
Errors
- “fields cannot be empty.”
- “Unknown entity.” with a hint.
- For a data model record: “Validation failed.” with the fields to fix.
- For a system object, the text names the field, for example
Invalid value for type_id.orField "country_id" is required on "shipment".Some fields add a hint where to put the value.