0
# CRUD Operations
1

2
Core create, retrieve, update, and delete operations for CRM entities with support for alternate keys, OData query parameters, FetchXML queries, and automatic pagination handling.
3

4
## Capabilities
5

6
### Create Operation
7

8
Creates new records in CRM entities with optional return of the created record.
9

10
```typescript { .api }
11
/**
12
 * Create a new record in the specified entity
13
 * @param parameters - Create operation parameters
14
 * @returns Promise resolving to the created record ID or full record (with Prefer header)
15
 */
16
function Create(parameters: CreateParameters): Promise<string> | Promise<any> | string | any | BatchRequest;
17

18
interface CreateParameters extends BaseParameters {
19
    /** Entity logical name (e.g., "account", "contact") */
20
    entityName?: string;
21
    /** Override for non-standard entity set names */
22
    overriddenSetName?: string;
23
    /** Data object containing the field values to create */
24
    entity: object;
25
}
26
```
27

28
**Usage Examples:**
29

30
```typescript
31
// Basic create
32
const accountId = await WebApiClient.Create({
33
    entityName: "account",
34
    entity: {
35
        name: "Contoso Corporation",
36
        telephone1: "555-0123",
37
        websiteurl: "https://contoso.com"
38
    }
39
});
40

41
// Create with return representation
42
const createdAccount = await WebApiClient.Create({
43
    entityName: "account",
44
    entity: { name: "Adventure Works" },
45
    headers: [{ key: "Prefer", value: "return=representation" }]
46
});
47

48
// Create with lookup relationship
49
await WebApiClient.Create({
50
    entityName: "contact",
51
    entity: {
52
        firstname: "John",
53
        lastname: "Doe",
54
        "parentcustomerid_account@odata.bind": "/accounts(" + accountId + ")"
55
    }
56
});
57

58
// Synchronous create
59
const syncResult = WebApiClient.Create({
60
    entityName: "account",
61
    entity: { name: "Sync Account" },
62
    async: false
63
});
64
```
65

66
### Retrieve Operations
67

68
Retrieves records using entity ID, alternate keys, OData queries, or FetchXML with automatic pagination support.
69

70
```typescript { .api }
71
/**
72
 * Retrieve records from CRM entities
73
 * @param parameters - Retrieve operation parameters
74
 * @returns Promise resolving to single record or array of records
75
 */
76
function Retrieve(parameters: RetrieveParameters): Promise<any> | any | BatchRequest;
77

78
interface RetrieveParameters extends BaseParameters {
79
    /** Entity logical name */
80
    entityName?: string;
81
    /** Override for non-standard entity set names */
82
    overriddenSetName?: string;
83
    /** Record GUID for single record retrieval */
84
    entityId?: string;
85
    /** Alternate key criteria for single record retrieval */
86
    alternateKey?: Array<Key>;
87
    /** OData query parameters (e.g., "?$select=name&$filter=...") */
88
    queryParams?: string;
89
    /** FetchXML query string for complex queries */
90
    fetchXml?: string;
91
    /** Override global pagination setting */
92
    returnAllPages?: boolean;
93
}
94

95
interface Key {
96
    property: string;
97
    value: string | number;
98
}
99
```
100

101
**Usage Examples:**
102

103
```typescript
104
// Retrieve by ID
105
const account = await WebApiClient.Retrieve({
106
    entityName: "account",
107
    entityId: "12345678-1234-1234-1234-123456789abc",
108
    queryParams: "?$select=name,telephone1,websiteurl"
109
});
110

111
// Retrieve by alternate key
112
const contact = await WebApiClient.Retrieve({
113
    entityName: "contact",
114
    alternateKey: [
115
        { property: "emailaddress1", value: "john.doe@contoso.com" }
116
    ]
117
});
118

119
// Retrieve multiple with OData
120
const activeAccounts = await WebApiClient.Retrieve({
121
    entityName: "account",
122
    queryParams: "?$select=name,revenue&$filter=statecode eq 0&$orderby=name",
123
    returnAllPages: true
124
});
125

126
// Retrieve with FetchXML
127
const accountsWithContacts = await WebApiClient.Retrieve({
128
    entityName: "account",
129
    fetchXml: `
130
        <fetch mapping='logical' count='10'>
131
            <entity name='account'>
132
                <attribute name='name'/>
133
                <attribute name='telephone1'/>
134
                <link-entity name='contact' from='parentcustomerid' to='accountid'>
135
                    <attribute name='fullname'/>
136
                    <attribute name='emailaddress1'/>
137
                </link-entity>
138
            </entity>
139
        </fetch>`
140
});
141

142
// Retrieve with expanded collection properties
143
const accountsWithContacts = await WebApiClient.Retrieve({
144
    entityName: "account",
145
    queryParams: "?$expand=contact_customer_accounts($select=fullname,emailaddress1)"
146
});
147

148
// Handle expanded results
149
console.log("Accounts with contacts:", accountsWithContacts.value);
150
```
151

152
### Update Operation
153

154
Updates existing records using entity ID or alternate keys with optional return of updated record.
155

156
```typescript { .api }
157
/**
158
 * Update an existing record
159
 * @param parameters - Update operation parameters
160
 * @returns Promise resolving to update confirmation or updated record
161
 */
162
function Update(parameters: UpdateParameters): Promise<string> | Promise<any> | string | any | BatchRequest;
163

164
interface UpdateParameters extends BaseParameters {
165
    /** Entity logical name */
166
    entityName?: string;
167
    /** Override for non-standard entity set names */
168
    overriddenSetName?: string;
169
    /** Record GUID to update */
170
    entityId?: string;
171
    /** Data object containing field values to update */
172
    entity: object;
173
    /** Alternate key criteria for identifying record to update */
174
    alternateKey?: Array<Key>;
175
}
176
```
177

178
**Usage Examples:**
179

180
```typescript
181
// Basic update by ID
182
await WebApiClient.Update({
183
    entityName: "account",
184
    entityId: "12345678-1234-1234-1234-123456789abc",
185
    entity: {
186
        name: "Updated Account Name",
187
        telephone1: "555-9999"
188
    }
189
});
190

191
// Update by alternate key
192
await WebApiClient.Update({
193
    entityName: "contact",
194
    alternateKey: [
195
        { property: "emailaddress1", value: "john.doe@contoso.com" }
196
    ],
197
    entity: { lastname: "Smith" }
198
});
199

200
// Update with return representation
201
const updatedAccount = await WebApiClient.Update({
202
    entityName: "account",
203
    entityId: accountId,
204
    entity: { name: "New Name" },
205
    headers: [{ key: "Prefer", value: "return=representation" }]
206
});
207

208
// Clear a lookup field (use Delete operation for lookups)
209
await WebApiClient.Delete({
210
    entityName: "account",
211
    entityId: accountId,
212
    queryParams: "/primarycontactid/$ref"
213
});
214

215
// Upsert operation (update if exists, create if not)
216
await WebApiClient.Update({
217
    entityName: "contact",
218
    alternateKey: [
219
        { property: "emailaddress1", value: "new.contact@contoso.com" }
220
    ],
221
    entity: { firstname: "Jane", lastname: "Doe" }
222
    // Note: This is upsert by default with alternate key
223
});
224
```
225

226
### Delete Operation
227

228
Deletes records by entity ID, alternate keys, or specific field properties with support for lookup field clearing.
229

230
```typescript { .api }
231
/**
232
 * Delete a record or clear a field property
233
 * @param parameters - Delete operation parameters
234
 * @returns Promise resolving to delete confirmation
235
 */
236
function Delete(parameters: DeleteParameters): Promise<string> | string | BatchRequest;
237

238
interface DeleteParameters extends BaseParameters {
239
    /** Entity logical name */
240
    entityName?: string;
241
    /** Override for non-standard entity set names */
242
    overriddenSetName?: string;
243
    /** Record GUID to delete */
244
    entityId?: string;
245
    /** Alternate key criteria for identifying record to delete */
246
    alternateKey?: Array<Key>;
247
    /** Query parameters for field deletion (e.g., "/fieldname" or "/lookupfield/$ref") */
248
    queryParams?: string;
249
}
250
```
251

252
**Usage Examples:**
253

254
```typescript
255
// Delete by ID
256
await WebApiClient.Delete({
257
    entityName: "account",
258
    entityId: "12345678-1234-1234-1234-123456789abc"
259
});
260

261
// Delete by alternate key
262
await WebApiClient.Delete({
263
    entityName: "contact",
264
    alternateKey: [
265
        { property: "emailaddress1", value: "obsolete.contact@contoso.com" }
266
    ]
267
});
268

269
// Clear a regular field
270
await WebApiClient.Delete({
271
    entityName: "account",
272
    entityId: accountId,
273
    queryParams: "/telephone1"
274
});
275

276
// Clear a lookup field
277
await WebApiClient.Delete({
278
    entityName: "account",
279
    entityId: accountId,
280
    queryParams: "/primarycontactid/$ref"
281
});
282
```
283

284
### Collection Property Expansion
285

286
Use $expand query parameter to retrieve related records in a single request.
287

288
**Usage Example:**
289

290
```typescript
291
// Retrieve with collection expansion
292
const accountsWithContacts = await WebApiClient.Retrieve({
293
    entityName: "account",
294
    queryParams: "?$select=name&$expand=contact_customer_accounts($select=fullname,emailaddress1)"
295
});
296

297
// Process expanded collections
298
for (const account of accountsWithContacts.value) {
299
    console.log(`Account: ${account.name}`);
300
    if (account.contact_customer_accounts) {
301
        for (const contact of account.contact_customer_accounts) {
302
            console.log(`- Contact: ${contact.fullname} (${contact.emailaddress1})`);
303
        }
304
    }
305
}
306
```
307

308
## Global Configuration
309

310
```typescript { .api }
311
/** Override global pagination behavior */
312
let ReturnAllPages: boolean;
313
```
314

315
**Configuration Example:**
316

317
```typescript
318
// Enable automatic pagination for all retrieve operations
319
WebApiClient.ReturnAllPages = true;
320

321
// Configure multiple settings
322
WebApiClient.ReturnAllPages = true;
323
WebApiClient.ApiVersion = "9.0";
324
WebApiClient.PrettifyErrors = false;
325
```